fleet-waitlist-submit 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# fleet-waitlist-submit
+
+Server-side helper that commits waitlist signups as markdown to a developer's vault repo on GitHub. Part of the [Fleet](https://github.com/BiscayneDev/fleet) GTM toolkit.
+
+## How it fits
+
+```
+Visitor's browser
+  └─ <form> on your landing page
+       └─ POST to YOUR API route
+            └─ fleet-waitlist-submit (this package)
+                 └─ GitHub commit → your vault repo
+                      └─ Fleet (running locally) sees the file,
+                         matches against your contacts, notifies you
+```
+
+The submission flow is **markdown-first**: the signup IS a file in your vault, not a row in a DB that maps to a file. No third-party form service required.
+
+## Install
+
+```bash
+npm install fleet-waitlist-submit
+```
+
+## Use
+
+```ts
+// app/api/waitlist/route.ts (Next.js example)
+import { submit } from 'fleet-waitlist-submit'
+
+export async function POST(req: Request) {
+  const body = await req.json()
+
+  const result = await submit({
+    githubToken: process.env.GITHUB_TOKEN!,    // PAT with contents:write
+    vaultRepo: 'biscaynedev/halsey-vault',     // owner/repo
+    product: 'inference',                       // your product slug
+    email: body.email,
+    name: body.name,
+    context: body.context,
+    source: 'web-form',
+    honeypot: body.website,                     // see "Spam protection" below
+  })
+
+  if (!result.ok) {
+    return Response.json({ error: result.error }, { status: 400 })
+  }
+  return Response.json({ ok: true })
+}
+```
+
+## API
+
+```ts
+submit({
+  githubToken: string,        // GitHub PAT with contents:write on the vault repo
+  vaultRepo: string,          // "owner/repo"
+  vaultBranch?: string,       // defaults to repo's default branch
+  product: string,            // lowercase letters, numbers, dashes
+  email: string,              // RFC-ish validated
+  name?: string,
+  context?: string,
+  source?: string,
+  honeypot?: string,          // if non-empty, silently discards
+}) => Promise<SubmitResult>
+```
+
+Returns `{ ok: true, signupId, commitSha, path }` on success, `{ ok: true, discarded: true }` on honeypot hit, or `{ ok: false, error }` on validation/API failure.
+
+## What it writes
+
+A new file at `waitlists/<product>/signups/<timestamp-random>.md` in your vault repo:
+
+```yaml
+---
+id: 2026-05-16T14-32-19-987Z-3f4a8c2d1e
+product: inference
+email: chris@usepod.ai
+name: Chris G
+source: web-form
+createdAt: 2026-05-16T14:32:19.987Z
+---
+
+Building agent infra
+```
+
+Emails are normalized (lowercase, trimmed, `+alias` stripped) before storage to match Fleet's matcher convention.
+
+## Spam protection
+
+- **Honeypot:** Add a hidden form field (e.g. `<input type="text" name="website" tabindex="-1" autocomplete="off" style="position:absolute;left:-9999px">`). Bots fill it; humans don't. Pass it as `honeypot`. Filled means silent discard — bots don't learn they're caught.
+- **Rate limit at your API route**, not in this package. Helper has no opinion on that.
+- For high-volume forms, add Turnstile/hCaptcha in your handler and only call `submit()` after verification.
+
+## GitHub token scope
+
+Create a fine-grained PAT at <https://github.com/settings/tokens?type=beta> with:
+- Repository access: only the vault repo
+- Permissions: **Contents: read and write**
+
+Store it as `GITHUB_TOKEN` in your server's env. **Never expose it client-side.**
+
+## Related
+
+- [Fleet](https://github.com/BiscayneDev/fleet) — the local-first GTM brain that watches your vault and runs match logic
+- [fleet-waitlist-widget](../waitlist-widget) — drop-in React form that posts to your handler
+
+## License
+
+MIT © Halsey Huth

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Input to the submit() helper.
+ *
+ * Call this from your landing page's server-side form handler. It commits
+ * a markdown file under `waitlists/<product>/signups/<id>.md` in the
+ * developer's vault repo. Fleet running locally watches the vault and
+ * runs match logic against the dev's contacts.
+ */
+export interface SubmitInput {
+    /** GitHub PAT with `contents:write` on the vault repo. */
+    githubToken: string;
+    /** Vault repo as `owner/repo`. e.g. `biscaynedev/halsey-vault`. */
+    vaultRepo: string;
+    /** Branch to commit to. Defaults to the repo's default branch. */
+    vaultBranch?: string;
+    /** Product slug (lowercase letters, numbers, dashes). */
+    product: string;
+    /** Submitter's email — required, validated. */
+    email: string;
+    /** Optional submitter name. */
+    name?: string;
+    /** Optional free-text context ("what are you building?"). */
+    context?: string;
+    /** Optional submission source (e.g. 'web-form', 'twitter-dm'). */
+    source?: string;
+    /** Honeypot field — if non-empty, the submission is silently dropped. */
+    honeypot?: string;
+}
+export type SubmitResult = {
+    ok: true;
+    signupId: string;
+    commitSha: string;
+    path: string;
+} | {
+    ok: true;
+    discarded: true;
+    signupId: 'discarded';
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Commit a waitlist signup as a markdown file to a vault repo.
+ *
+ * Idempotency note: the signupId includes a random suffix, so the same
+ * email can be submitted multiple times without conflict (Fleet's
+ * matcher dedupes by email when surfacing matches, not by file). If
+ * you need strict one-per-email semantics, dedupe in your form handler
+ * before calling.
+ */
+export declare function submit(input: SubmitInput): Promise<SubmitResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAoBD,MAAM,MAAM,YAAY,GACpB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,GACD;IACE,EAAE,EAAE,IAAI,CAAC;IACT,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,EAAE,WAAW,CAAC;CACvB,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAuCN;;;;;;;;GAQG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAiDtE"}

package/dist/index.js

@@ -0,0 +1,107 @@
+import { randomBytes } from 'node:crypto';
+import { Octokit } from '@octokit/rest';
+import matter from 'gray-matter';
+import { z } from 'zod';
+const submitInputSchema = z.object({
+    githubToken: z.string().min(1),
+    vaultRepo: z
+        .string()
+        .regex(/^[^/\s]+\/[^/\s]+$/, 'vaultRepo must be in owner/repo form'),
+    vaultBranch: z.string().optional(),
+    product: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9-]*$/, {
+        message: 'product must be lowercase alphanumerics and dashes',
+    }),
+    email: z.email().max(254),
+    name: z.string().max(200).optional(),
+    context: z.string().max(2000).optional(),
+    source: z.string().max(50).optional(),
+    honeypot: z.string().optional(),
+});
+function normalizeEmail(email) {
+    const trimmed = email.trim().toLowerCase();
+    const atIdx = trimmed.lastIndexOf('@');
+    if (atIdx < 0)
+        return trimmed;
+    const local = trimmed.slice(0, atIdx);
+    const domain = trimmed.slice(atIdx);
+    const plusIdx = local.indexOf('+');
+    if (plusIdx < 0)
+        return trimmed;
+    return local.slice(0, plusIdx) + domain;
+}
+function makeSignupId() {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const rand = randomBytes(5).toString('hex');
+    return `${ts}-${rand}`;
+}
+function renderSignupMarkdown(opts) {
+    const frontmatter = {
+        id: opts.signupId,
+        product: opts.product,
+        email: opts.email,
+        createdAt: opts.createdAt,
+    };
+    if (opts.name)
+        frontmatter.name = opts.name;
+    if (opts.source)
+        frontmatter.source = opts.source;
+    return matter.stringify(opts.context, frontmatter);
+}
+/**
+ * Commit a waitlist signup as a markdown file to a vault repo.
+ *
+ * Idempotency note: the signupId includes a random suffix, so the same
+ * email can be submitted multiple times without conflict (Fleet's
+ * matcher dedupes by email when surfacing matches, not by file). If
+ * you need strict one-per-email semantics, dedupe in your form handler
+ * before calling.
+ */
+export async function submit(input) {
+    const parsed = submitInputSchema.safeParse(input);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            error: parsed.error.issues
+                .map((i) => `${i.path.join('.')}: ${i.message}`)
+                .join('; '),
+        };
+    }
+    // Honeypot — silently accept and drop
+    if (parsed.data.honeypot && parsed.data.honeypot.trim().length > 0) {
+        return { ok: true, discarded: true, signupId: 'discarded' };
+    }
+    const data = parsed.data;
+    const [owner, repo] = data.vaultRepo.split('/');
+    const octokit = new Octokit({ auth: data.githubToken });
+    const signupId = makeSignupId();
+    const createdAt = new Date().toISOString();
+    const path = `waitlists/${data.product}/signups/${signupId}.md`;
+    const content = renderSignupMarkdown({
+        signupId,
+        product: data.product,
+        email: normalizeEmail(data.email),
+        name: data.name,
+        source: data.source,
+        createdAt,
+        context: data.context ?? '',
+    });
+    try {
+        const res = await octokit.repos.createOrUpdateFileContents({
+            owner,
+            repo,
+            path,
+            message: `waitlist: ${data.product} signup`,
+            content: Buffer.from(content, 'utf8').toString('base64'),
+            branch: data.vaultBranch,
+        });
+        const commitSha = res.data.commit.sha ?? '';
+        return { ok: true, signupId, commitSha, path };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `GitHub commit failed: ${message}` };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "fleet-waitlist-submit",
+  "version": "0.1.0",
+  "description": "Server-side helper that commits waitlist signups as markdown to a developer's vault repo on GitHub. Part of the Fleet GTM toolkit.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "fleet",
+    "waitlist",
+    "obsidian",
+    "vault",
+    "github",
+    "markdown",
+    "gtm"
+  ],
+  "author": "Halsey Huth <halsey.huth@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BiscayneDev/fleet.git",
+    "directory": "packages/waitlist-submit"
+  },
+  "homepage": "https://github.com/BiscayneDev/fleet/tree/main/packages/waitlist-submit#readme",
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "dependencies": {
+    "@octokit/rest": "^22.0.1",
+    "gray-matter": "^4.0.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5",
+    "vitest": "^3.2.4"
+  }
+}