flagwire-typegen 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlagWire contributors
+
+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,12 @@
+# `flagwire-typegen`
+
+Generate TypeScript flag declarations from a FlagWire project.
+
+```sh
+npx flagwire-typegen \
+  --key "$FLAGWIRE_SERVER_KEY" \
+  --out src/flags.gen.ts
+```
+
+The key may be supplied through `FLAGWIRE_SERVER_KEY` instead of `--key`. Generated files are
+written atomically. Never commit a server key.

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface TypegenManifest {
+    flags: Array<{
+        key: string;
+        type: "boolean" | "json" | "string";
+        variants: Array<{
+            key: string;
+            value: JsonValue;
+        }>;
+    }>;
+    projectId: string;
+}
+export declare function generateTypes(manifest: TypegenManifest): string;
+export declare function run(argv?: string[]): Promise<void>;
+export {};

package/dist/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import{realpathSync as y}from"node:fs";import{mkdir as d,rename as w,writeFile as m}from"node:fs/promises";import{dirname as h,resolve as f}from"node:path";import{pathToFileURL as v}from"node:url";function k(t){return JSON.stringify(t)}function b(t){if(t.type==="boolean")return"boolean";let r=t.variants.map(e=>e.value).filter(e=>t.type==="json"||typeof e=="string").map(k);return[...new Set(r)].join(" | ")||"never"}function E(t){return t.flags.map(r=>`    readonly ${JSON.stringify(r.key)}: ${b(r)};`).join(`
+`)}function j(t){let r=t.flags.map(n=>JSON.stringify(n.key)).join(" | ")||"never",e=E(t);return`/* Generated by flagwire-typegen. Do not edit manually. */
+import type {} from "@flagwire/sdk-js";
+import type {} from "@flagwire/sdk-node";
+
+export type FlagKey = ${r};
+
+export interface FlagwireGeneratedFlags {
+${e}
+}
+
+declare module "@flagwire/sdk-js" {
+  interface FlagwireFlags {
+${e}
+  }
+}
+
+declare module "@flagwire/sdk-node" {
+  interface FlagwireFlags {
+${e}
+  }
+}
+
+export {};
+`}function F(t){let r=new Map;for(let e=0;e<t.length;e+=1){let n=t[e];if(n==="--help"||n==="-h")return{help:!0};if(!n.startsWith("--"))throw new Error(`Unknown argument: ${n}`);let o=n.indexOf("="),s=n.slice(2,o===-1?void 0:o),i=o===-1?t[++e]:n.slice(o+1);if(!i||i.startsWith("--"))throw new Error(`Missing value for --${s}`);if(!["base-url","key","out","project"].includes(s))throw new Error(`Unknown option: --${s}`);r.set(s,i)}return{help:!1,values:r}}function $(t){if(!t||typeof t!="object")return!1;let r=t;return typeof r.projectId=="string"&&Array.isArray(r.flags)&&r.flags.every(e=>e!==null&&typeof e=="object"&&typeof e.key=="string"&&(e.type==="boolean"||e.type==="string"||e.type==="json")&&Array.isArray(e.variants)&&e.variants.every(n=>n!==null&&typeof n=="object"&&typeof n.key=="string"&&"value"in n))}async function _(t=process.argv.slice(2)){let r=F(t);if(r.help){process.stdout.write(`Usage: flagwire-typegen --key sk_live_... --out src/flags.gen.ts [--project project_id] [--base-url https://api.flagwire.dev]
+`);return}let e=r.values.get("key")??process.env.FLAGWIRE_SERVER_KEY,n=r.values.get("out");if(!e||!/^sk_live_[A-Za-z0-9_-]{43}$/.test(e))throw new Error("Provide a valid server key with --key or FLAGWIRE_SERVER_KEY");if(!n)throw new Error("Provide an output path with --out");let o=new URL(r.values.get("base-url")??"https://api.flagwire.dev");if(o.protocol!=="https:"&&o.protocol!=="http:")throw new Error("--base-url must use http or https");if(o.username||o.password)throw new Error("--base-url cannot contain credentials");let s=r.values.get("project"),i=s?`/v1/typegen/${encodeURIComponent(s)}`:"/v1/typegen",a=await fetch(new URL(i,o),{headers:{Authorization:`Bearer ${e}`},signal:AbortSignal.timeout(15e3)});if(!a.ok)throw new Error(`FlagWire type generation failed with HTTP ${a.status}`);let u=Number(a.headers.get("Content-Length"));if(Number.isFinite(u)&&u>1048576)throw new Error("FlagWire type manifest exceeded 1MB");let c=await a.text();if(c.length>1048576)throw new Error("FlagWire type manifest exceeded 1MB");let l;try{l=JSON.parse(c)}catch{throw new Error("FlagWire returned an invalid type manifest")}if(!$(l))throw new Error("FlagWire returned an invalid type manifest");let p=f(n),g=`${p}.${process.pid}.tmp`;await d(h(p),{recursive:!0}),await m(g,j(l),{encoding:"utf8",mode:420}),await w(g,p),process.stdout.write(`Generated ${l.flags.length} FlagWire flag types in ${p}
+`)}var x=process.argv[1]?v(y(f(process.argv[1]))).href:"";import.meta.url===x&&_().catch(t=>{process.stderr.write(`${t instanceof Error?t.message:"Type generation failed"}
+`),process.exitCode=1});export{j as generateTypes,_ as run};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "flagwire-typegen",
+  "version": "0.1.0",
+  "description": "Generate type-safe FlagWire flag definitions",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "flagwire-typegen": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flagwire/flagwire-js.git",
+    "directory": "tools/typegen-cli"
+  },
+  "publishConfig": {
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "24.3.0",
+    "esbuild": "0.28.2"
+  },
+  "scripts": {
+    "build": "node ../../scripts/clean-package-dist.mjs && tsc -p tsconfig.build.json && esbuild src/index.ts --bundle --minify --format=esm --platform=node --target=node20 --outfile=dist/index.js",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}