pocketbomb-dynamite 0.0.0-stage → 0.2.0

package/LICENSE.md

@@ -0,0 +1,17 @@
+The MIT License (MIT)
+Copyright (c) 2026 - present, the PocketBomb 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

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# pocketbomb-dynamite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The PocketBomb storefront framework (similar to Hydrogen).
+
+```ts
+import { createRequestContext, createStorefrontClient, gql, MemoryCache } from "pocketbomb-dynamite";
+import { createCustomerAccountClient } from "pocketbomb-dynamite/customer-account";
+
+const cache = new MemoryCache();
+
+export async function handle(request: Request) {
+  const context = createRequestContext({ request, cache }); // buyer IP, cookie session, cache
+  const storefront = createStorefrontClient({ url, privateKey, requestContext: context });
+  const customer = createCustomerAccountClient({
+    url, collection: "users", clientId, redirectUri, requestContext: context,
+  });
+
+  const path = new URL(request.url).pathname;
+  if (path === "/account/login") return customer.loginRedirect({ returnTo: "/account" });
+  if (path === "/account/callback") return customer.callbackRedirect();
+  if (path === "/account/logout") return customer.logoutRedirect();
+
+  const { products } = await storefront.query(PRODUCTS, { variables: { first: 10 } });
+  const response = new Response(render(products, customer.isLoggedIn()));
+  context.applyResponseHeaders(response.headers); // Set-Cookie + private caching
+  return response;
+}
+
+const PRODUCTS = gql<{ products: { nodes: Array<{ id: string; title: string }> } }, { first: number }>(
+  `query Products($first: Int) { products(first: $first) { nodes { id title } } }`,
+);
+```
+
+Entries: `pocketbomb-dynamite` (core + storefront client + GraphQL), `pocketbomb-dynamite/customer-account`,
+`pocketbomb-dynamite/graphql` (gql.tada `graphql()` typed by `dynamite codegen`), `pocketbomb-dynamite/react`
+(DynamiteProvider, useStorefront, useCustomer, useStorefrontQuery, Pagination, FileImage), `pocketbomb-dynamite/vite`
+(env + private key guard, dev proxy, codegen, fuse) and `pocketbomb-dynamite/ts-plugin` (graphqlsp for the editor).
+
+CLI: `dynamite codegen [--watch] [--fuse --seed <module>]`, `dynamite dev [--seed] [--entry server.ts]`, `dynamite info`.

package/bin/dynamite.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { run } from "../dist/cli/index.js";
+
+run(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err) => {
+    console.error(err);
+    process.exit(1);
+  },
+);

package/dist/_virtual/_rolldown/runtime.cjs

@@ -0,0 +1,22 @@
+// \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+exports.__toESM = __toESM;

package/dist/cli/codegen.cjs

@@ -0,0 +1,120 @@
+const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
+const require_constants = require("../shared/constants.cjs");
+let node_fs = require("node:fs");
+node_fs = require_runtime.__toESM(node_fs, 1);
+let node_path = require("node:path");
+node_path = require_runtime.__toESM(node_path, 1);
+let _gql_tada_internal = require("@gql.tada/internal");
+let graphql = require("graphql");
+// src/cli/codegen.ts
+/**
+* Introspects the PocketBomb GraphQL API (`POST /api/graphql`; the introspection
+* fields are not counted in the query limits).
+*
+* @throws {Error} for the HTTP and GraphQL errors.
+*/
+async function introspect(options) {
+	const headers = { "content-type": "application/json" };
+	if (options.publicKey) headers["X-PB-Public-Key"] = options.publicKey;
+	const endpoint = options.url.replace(/\/+$/, "") + "/api/graphql";
+	const response = await (options.fetch || fetch)(endpoint, {
+		method: "POST",
+		headers,
+		body: JSON.stringify({ query: (0, graphql.getIntrospectionQuery)({ descriptions: true }) })
+	});
+	let body = null;
+	try {
+		body = await response.json();
+	} catch {
+		body = null;
+	}
+	if (!response.ok) throw new Error(`The GraphQL introspection failed (${response.status}): ${body?.message || JSON.stringify(body)}`);
+	if (body?.errors?.length || !body?.data?.__schema) throw new Error("The GraphQL introspection failed: " + (body?.errors?.map((e) => e.message).join("; ") || "no schema"));
+	return body.data;
+}
+/**
+* Returns a copy of the introspection without the empty descriptions
+* (the server reports "" for the undocumented fields).
+*/
+function withoutEmptyDescriptions(value) {
+	if (Array.isArray(value)) return value.map(withoutEmptyDescriptions);
+	if (value && typeof value === "object") {
+		const result = {};
+		for (const [key, item] of Object.entries(value)) result[key] = key === "description" && item === "" ? null : withoutEmptyDescriptions(item);
+		return result;
+	}
+	return value;
+}
+/**
+* Returns the GraphQL SDL of an introspection.
+*/
+function introspectionToSDL(introspection) {
+	return (0, graphql.printSchema)((0, graphql.buildClientSchema)(withoutEmptyDescriptions(introspection))) + "\n";
+}
+/**
+* Returns the `pocketbomb-env.d.ts` of an introspection: the gql.tada introspection type
+* and the `pocketbomb-dynamite/graphql` schema augmentation used by `graphql()`.
+*/
+function introspectionToEnv(introspection) {
+	return "/* eslint-disable */\n/* prettier-ignore */\n// Generated by `dynamite codegen` from the PocketBomb GraphQL API. Do not edit.\n\n/** The gql.tada introspection of the PocketBomb GraphQL schema. */\nexport type introspection = " + (0, _gql_tada_internal.preprocessIntrospection)((0, _gql_tada_internal.minifyIntrospection)(introspection)) + ";\n\ndeclare module \"pocketbomb-dynamite/graphql\" {\n  interface PocketBombSchema {\n    introspection: introspection;\n  }\n}\n";
+}
+function writeIfChanged(file, content) {
+	if (node_fs.default.existsSync(file) && node_fs.default.readFileSync(file, "utf8") === content) return false;
+	node_fs.default.mkdirSync(node_path.default.dirname(file), { recursive: true });
+	node_fs.default.writeFileSync(file, content);
+	return true;
+}
+/**
+* Writes the schema SDL and the gql.tada env of an introspection (only if they changed).
+*/
+function generate(introspection, options = {}) {
+	const cwd = options.cwd || process.cwd();
+	const schemaFile = node_path.default.resolve(cwd, options.schemaFile || ".dynamite/schema.graphql");
+	const envFile = node_path.default.resolve(cwd, options.envFile || "pocketbomb-env.d.ts");
+	const schemaChanged = writeIfChanged(schemaFile, introspectionToSDL(introspection));
+	const envChanged = writeIfChanged(envFile, introspectionToEnv(introspection));
+	return {
+		schemaFile,
+		envFile,
+		changed: schemaChanged || envChanged
+	};
+}
+/**
+* Introspects the API and writes the schema and the env (see {@link generate}).
+*/
+async function codegen(options) {
+	return generate(await introspect(options), options);
+}
+/**
+* Regenerates the schema and the env when the API schema changes (polling).
+* Returns a function that stops the watcher.
+*/
+function watchCodegen(options) {
+	let stopped = false;
+	let timer;
+	const tick = async () => {
+		try {
+			const result = await codegen(options);
+			if (result.changed) options.onChange?.(result);
+		} catch (err) {
+			options.onError?.(err);
+		}
+		if (!stopped) timer = setTimeout(tick, options.interval ?? 2e3);
+	};
+	tick();
+	return () => {
+		stopped = true;
+		clearTimeout(timer);
+	};
+}
+exports.DEFAULT_ENV_FILE = require_constants.DEFAULT_ENV_FILE;
+exports.DEFAULT_SCHEMA_FILE = require_constants.DEFAULT_SCHEMA_FILE;
+exports.codegen = codegen;
+exports.generate = generate;
+exports.introspect = introspect;
+exports.introspectionToEnv = introspectionToEnv;
+exports.introspectionToSDL = introspectionToSDL;
+exports.watchCodegen = watchCodegen;
+exports.withoutEmptyDescriptions = withoutEmptyDescriptions;
+
+//# sourceMappingURL=codegen.cjs.map

package/dist/cli/codegen.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.cjs","names":["getIntrospectionQuery","printSchema","buildClientSchema","preprocessIntrospection","minifyIntrospection","fs","path"],"sources":["../../src/cli/codegen.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { minifyIntrospection, preprocessIntrospection } from \"@gql.tada/internal\";\nimport {\n  buildClientSchema,\n  getIntrospectionQuery,\n  printSchema,\n  type IntrospectionQuery,\n} from \"graphql\";\n\nimport { DEFAULT_ENV_FILE, DEFAULT_SCHEMA_FILE } from \"../shared/constants\";\n\nexport { DEFAULT_ENV_FILE, DEFAULT_SCHEMA_FILE };\n\nexport interface IntrospectOptions {\n  /** The PocketBomb URL. */\n  url: string;\n  /** The public API key (the GraphQL API requires client credentials). */\n  publicKey?: string;\n  fetch?: typeof fetch;\n}\n\n/**\n * Introspects the PocketBomb GraphQL API (`POST /api/graphql`; the introspection\n * fields are not counted in the query limits).\n *\n * @throws {Error} for the HTTP and GraphQL errors.\n */\nexport async function introspect(options: IntrospectOptions): Promise<IntrospectionQuery> {\n  const headers: Record<string, string> = { \"content-type\": \"application/json\" };\n  if (options.publicKey) {\n    headers[\"X-PB-Public-Key\"] = options.publicKey;\n  }\n\n  const endpoint = options.url.replace(/\\/+$/, \"\") + \"/api/graphql\";\n  const response = await (options.fetch || fetch)(endpoint, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify({ query: getIntrospectionQuery({ descriptions: true }) }),\n  });\n\n  let body: any = null;\n  try {\n    body = await response.json();\n  } catch {\n    body = null;\n  }\n\n  if (!response.ok) {\n    throw new Error(\n      `The GraphQL introspection failed (${response.status}): ${body?.message || JSON.stringify(body)}`,\n    );\n  }\n  if (body?.errors?.length || !body?.data?.__schema) {\n    throw new Error(\n      \"The GraphQL introspection failed: \" +\n        (body?.errors?.map((e: any) => e.message).join(\"; \") || \"no schema\"),\n    );\n  }\n\n  return body.data as IntrospectionQuery;\n}\n\n/**\n * Returns a copy of the introspection without the empty descriptions\n * (the server reports \"\" for the undocumented fields).\n */\nexport function withoutEmptyDescriptions<T>(value: T): T {\n  if (Array.isArray(value)) {\n    return value.map(withoutEmptyDescriptions) as T;\n  }\n\n  if (value && typeof value === \"object\") {\n    const result: Record<string, unknown> = {};\n    for (const [key, item] of Object.entries(value)) {\n      result[key] = key === \"description\" && item === \"\" ? null : withoutEmptyDescriptions(item);\n    }\n    return result as T;\n  }\n\n  return value;\n}\n\n/**\n * Returns the GraphQL SDL of an introspection.\n */\nexport function introspectionToSDL(introspection: IntrospectionQuery): string {\n  return printSchema(buildClientSchema(withoutEmptyDescriptions(introspection))) + \"\\n\";\n}\n\n/**\n * Returns the `pocketbomb-env.d.ts` of an introspection: the gql.tada introspection type\n * and the `pocketbomb-dynamite/graphql` schema augmentation used by `graphql()`.\n */\nexport function introspectionToEnv(introspection: IntrospectionQuery): string {\n  const type = preprocessIntrospection(minifyIntrospection(introspection));\n\n  return (\n    \"/* eslint-disable */\\n\" +\n    \"/* prettier-ignore */\\n\" +\n    \"// Generated by `dynamite codegen` from the PocketBomb GraphQL API. Do not edit.\\n\\n\" +\n    \"/** The gql.tada introspection of the PocketBomb GraphQL schema. */\\n\" +\n    \"export type introspection = \" +\n    type +\n    \";\\n\\n\" +\n    'declare module \"pocketbomb-dynamite/graphql\" {\\n' +\n    \"  interface PocketBombSchema {\\n\" +\n    \"    introspection: introspection;\\n\" +\n    \"  }\\n\" +\n    \"}\\n\"\n  );\n}\n\nexport interface GenerateOptions {\n  /** The project root (default to the current working dir). */\n  cwd?: string;\n  /** The SDL output (default to `.dynamite/schema.graphql`). */\n  schemaFile?: string;\n  /** The gql.tada env output (default to `pocketbomb-env.d.ts`). */\n  envFile?: string;\n}\n\nexport interface GenerateResult {\n  schemaFile: string;\n  envFile: string;\n  /** Whether a file was (re)written. */\n  changed: boolean;\n}\n\nfunction writeIfChanged(file: string, content: string): boolean {\n  if (fs.existsSync(file) && fs.readFileSync(file, \"utf8\") === content) {\n    return false;\n  }\n\n  fs.mkdirSync(path.dirname(file), { recursive: true });\n  fs.writeFileSync(file, content);\n\n  return true;\n}\n\n/**\n * Writes the schema SDL and the gql.tada env of an introspection (only if they changed).\n */\nexport function generate(\n  introspection: IntrospectionQuery,\n  options: GenerateOptions = {},\n): GenerateResult {\n  const cwd = options.cwd || process.cwd();\n  const schemaFile = path.resolve(cwd, options.schemaFile || DEFAULT_SCHEMA_FILE);\n  const envFile = path.resolve(cwd, options.envFile || DEFAULT_ENV_FILE);\n\n  const schemaChanged = writeIfChanged(schemaFile, introspectionToSDL(introspection));\n  const envChanged = writeIfChanged(envFile, introspectionToEnv(introspection));\n\n  return { schemaFile, envFile, changed: schemaChanged || envChanged };\n}\n\nexport interface CodegenOptions extends IntrospectOptions, GenerateOptions {}\n\n/**\n * Introspects the API and writes the schema and the env (see {@link generate}).\n */\nexport async function codegen(options: CodegenOptions): Promise<GenerateResult> {\n  return generate(await introspect(options), options);\n}\n\nexport interface WatchOptions extends CodegenOptions {\n  /** The schema poll interval in ms (default to 2000). */\n  interval?: number;\n  /** Called after every generation that changed a file. */\n  onChange?: (result: GenerateResult) => void;\n  /** Called for the failed polls (the watcher keeps running). */\n  onError?: (err: unknown) => void;\n}\n\n/**\n * Regenerates the schema and the env when the API schema changes (polling).\n * Returns a function that stops the watcher.\n */\nexport function watchCodegen(options: WatchOptions): () => void {\n  let stopped = false;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n\n  const tick = async () => {\n    try {\n      const result = await codegen(options);\n      if (result.changed) {\n        options.onChange?.(result);\n      }\n    } catch (err) {\n      options.onError?.(err);\n    }\n\n    if (!stopped) {\n      timer = setTimeout(tick, options.interval ?? 2000);\n    }\n  };\n\n  void tick();\n\n  return () => {\n    stopped = true;\n    clearTimeout(timer);\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;AA4BA,eAAsB,WAAW,SAAyD;CACxF,MAAM,UAAkC,EAAE,gBAAgB,mBAAmB;CAC7E,IAAI,QAAQ,WACV,QAAQ,qBAAqB,QAAQ;CAGvC,MAAM,WAAW,QAAQ,IAAI,QAAQ,QAAQ,EAAE,IAAI;CACnD,MAAM,WAAW,OAAO,QAAQ,SAAS,MAAA,CAAO,UAAU;EACxD,QAAQ;EACR;EACA,MAAM,KAAK,UAAU,EAAE,QAAA,GAAOA,QAAAA,sBAAAA,CAAsB,EAAE,cAAc,KAAK,CAAC,EAAE,CAAC;CAC/E,CAAC;CAED,IAAI,OAAY;CAChB,IAAI;EACF,OAAO,MAAM,SAAS,KAAK;CAC7B,QAAQ;EACN,OAAO;CACT;CAEA,IAAI,CAAC,SAAS,IACZ,MAAM,IAAI,MACR,qCAAqC,SAAS,OAAO,KAAK,MAAM,WAAW,KAAK,UAAU,IAAI,GAChG;CAEF,IAAI,MAAM,QAAQ,UAAU,CAAC,MAAM,MAAM,UACvC,MAAM,IAAI,MACR,wCACG,MAAM,QAAQ,KAAK,MAAW,EAAE,OAAO,CAAC,CAAC,KAAK,IAAI,KAAK,YAC5D;CAGF,OAAO,KAAK;AACd;;;;;AAMA,SAAgB,yBAA4B,OAAa;CACvD,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,IAAI,wBAAwB;CAG3C,IAAI,SAAS,OAAO,UAAU,UAAU;EACtC,MAAM,SAAkC,CAAC;EACzC,KAAK,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,KAAK,GAC5C,OAAO,OAAO,QAAQ,iBAAiB,SAAS,KAAK,OAAO,yBAAyB,IAAI;EAE3F,OAAO;CACT;CAEA,OAAO;AACT;;;;AAKA,SAAgB,mBAAmB,eAA2C;CAC5E,QAAA,GAAOC,QAAAA,YAAAA,EAAAA,GAAYC,QAAAA,kBAAAA,CAAkB,yBAAyB,aAAa,CAAC,CAAC,IAAI;AACnF;;;;;AAMA,SAAgB,mBAAmB,eAA2C;CAG5E,OACE,wOAAA,GAHWC,mBAAAA,wBAAAA,EAAAA,GAAwBC,mBAAAA,oBAAAA,CAAoB,aAAa,CAQjE,IACH;AAOJ;AAkBA,SAAS,eAAe,MAAc,SAA0B;CAC9D,IAAIC,QAAAA,QAAG,WAAW,IAAI,KAAKA,QAAAA,QAAG,aAAa,MAAM,MAAM,MAAM,SAC3D,OAAO;CAGT,QAAA,QAAG,UAAUC,UAAAA,QAAK,QAAQ,IAAI,GAAG,EAAE,WAAW,KAAK,CAAC;CACpD,QAAA,QAAG,cAAc,MAAM,OAAO;CAE9B,OAAO;AACT;;;;AAKA,SAAgB,SACd,eACA,UAA2B,CAAC,GACZ;CAChB,MAAM,MAAM,QAAQ,OAAO,QAAQ,IAAI;CACvC,MAAM,aAAaA,UAAAA,QAAK,QAAQ,KAAK,QAAQ,cAAA,0BAAiC;CAC9E,MAAM,UAAUA,UAAAA,QAAK,QAAQ,KAAK,QAAQ,WAAA,qBAA2B;CAErE,MAAM,gBAAgB,eAAe,YAAY,mBAAmB,aAAa,CAAC;CAClF,MAAM,aAAa,eAAe,SAAS,mBAAmB,aAAa,CAAC;CAE5E,OAAO;EAAE;EAAY;EAAS,SAAS,iBAAiB;CAAW;AACrE;;;;AAOA,eAAsB,QAAQ,SAAkD;CAC9E,OAAO,SAAS,MAAM,WAAW,OAAO,GAAG,OAAO;AACpD;;;;;AAeA,SAAgB,aAAa,SAAmC;CAC9D,IAAI,UAAU;CACd,IAAI;CAEJ,MAAM,OAAO,YAAY;EACvB,IAAI;GACF,MAAM,SAAS,MAAM,QAAQ,OAAO;GACpC,IAAI,OAAO,SACT,QAAQ,WAAW,MAAM;EAE7B,SAAS,KAAK;GACZ,QAAQ,UAAU,GAAG;EACvB;EAEA,IAAI,CAAC,SACH,QAAQ,WAAW,MAAM,QAAQ,YAAY,GAAI;CAErD;CAEA,KAAU;CAEV,aAAa;EACX,UAAU;EACV,aAAa,KAAK;CACpB;AACF"}

package/dist/cli/codegen.d.cts

@@ -0,0 +1,68 @@
+import { DEFAULT_ENV_FILE, DEFAULT_SCHEMA_FILE } from "../shared/constants.cjs";
+import { IntrospectionQuery } from "graphql";
+export interface IntrospectOptions {
+  /** The PocketBomb URL. */
+  url: string;
+  /** The public API key (the GraphQL API requires client credentials). */
+  publicKey?: string;
+  fetch?: typeof fetch;
+}
+/**
+ * Introspects the PocketBomb GraphQL API (`POST /api/graphql`; the introspection
+ * fields are not counted in the query limits).
+ *
+ * @throws {Error} for the HTTP and GraphQL errors.
+ */
+export declare function introspect(options: IntrospectOptions): Promise<IntrospectionQuery>;
+/**
+ * Returns a copy of the introspection without the empty descriptions
+ * (the server reports "" for the undocumented fields).
+ */
+export declare function withoutEmptyDescriptions<T>(value: T): T;
+/**
+ * Returns the GraphQL SDL of an introspection.
+ */
+export declare function introspectionToSDL(introspection: IntrospectionQuery): string;
+/**
+ * Returns the `pocketbomb-env.d.ts` of an introspection: the gql.tada introspection type
+ * and the `pocketbomb-dynamite/graphql` schema augmentation used by `graphql()`.
+ */
+export declare function introspectionToEnv(introspection: IntrospectionQuery): string;
+export interface GenerateOptions {
+  /** The project root (default to the current working dir). */
+  cwd?: string;
+  /** The SDL output (default to `.dynamite/schema.graphql`). */
+  schemaFile?: string;
+  /** The gql.tada env output (default to `pocketbomb-env.d.ts`). */
+  envFile?: string;
+}
+export interface GenerateResult {
+  schemaFile: string;
+  envFile: string;
+  /** Whether a file was (re)written. */
+  changed: boolean;
+}
+/**
+ * Writes the schema SDL and the gql.tada env of an introspection (only if they changed).
+ */
+export declare function generate(introspection: IntrospectionQuery, options?: GenerateOptions): GenerateResult;
+export interface CodegenOptions extends IntrospectOptions, GenerateOptions {}
+/**
+ * Introspects the API and writes the schema and the env (see {@link generate}).
+ */
+export declare function codegen(options: CodegenOptions): Promise<GenerateResult>;
+export interface WatchOptions extends CodegenOptions {
+  /** The schema poll interval in ms (default to 2000). */
+  interval?: number;
+  /** Called after every generation that changed a file. */
+  onChange?: (result: GenerateResult) => void;
+  /** Called for the failed polls (the watcher keeps running). */
+  onError?: (err: unknown) => void;
+}
+/**
+ * Regenerates the schema and the env when the API schema changes (polling).
+ * Returns a function that stops the watcher.
+ */
+export declare function watchCodegen(options: WatchOptions): () => void;
+export { DEFAULT_ENV_FILE, DEFAULT_SCHEMA_FILE };
+//# sourceMappingURL=codegen.d.cts.map

package/dist/cli/codegen.d.ts

@@ -0,0 +1,68 @@
+import { DEFAULT_ENV_FILE, DEFAULT_SCHEMA_FILE } from "../shared/constants.js";
+import { IntrospectionQuery } from "graphql";
+export interface IntrospectOptions {
+  /** The PocketBomb URL. */
+  url: string;
+  /** The public API key (the GraphQL API requires client credentials). */
+  publicKey?: string;
+  fetch?: typeof fetch;
+}
+/**
+ * Introspects the PocketBomb GraphQL API (`POST /api/graphql`; the introspection
+ * fields are not counted in the query limits).
+ *
+ * @throws {Error} for the HTTP and GraphQL errors.
+ */
+export declare function introspect(options: IntrospectOptions): Promise<IntrospectionQuery>;
+/**
+ * Returns a copy of the introspection without the empty descriptions
+ * (the server reports "" for the undocumented fields).
+ */
+export declare function withoutEmptyDescriptions<T>(value: T): T;
+/**
+ * Returns the GraphQL SDL of an introspection.
+ */
+export declare function introspectionToSDL(introspection: IntrospectionQuery): string;
+/**
+ * Returns the `pocketbomb-env.d.ts` of an introspection: the gql.tada introspection type
+ * and the `pocketbomb-dynamite/graphql` schema augmentation used by `graphql()`.
+ */
+export declare function introspectionToEnv(introspection: IntrospectionQuery): string;
+export interface GenerateOptions {
+  /** The project root (default to the current working dir). */
+  cwd?: string;
+  /** The SDL output (default to `.dynamite/schema.graphql`). */
+  schemaFile?: string;
+  /** The gql.tada env output (default to `pocketbomb-env.d.ts`). */
+  envFile?: string;
+}
+export interface GenerateResult {
+  schemaFile: string;
+  envFile: string;
+  /** Whether a file was (re)written. */
+  changed: boolean;
+}
+/**
+ * Writes the schema SDL and the gql.tada env of an introspection (only if they changed).
+ */
+export declare function generate(introspection: IntrospectionQuery, options?: GenerateOptions): GenerateResult;
+export interface CodegenOptions extends IntrospectOptions, GenerateOptions {}
+/**
+ * Introspects the API and writes the schema and the env (see {@link generate}).
+ */
+export declare function codegen(options: CodegenOptions): Promise<GenerateResult>;
+export interface WatchOptions extends CodegenOptions {
+  /** The schema poll interval in ms (default to 2000). */
+  interval?: number;
+  /** Called after every generation that changed a file. */
+  onChange?: (result: GenerateResult) => void;
+  /** Called for the failed polls (the watcher keeps running). */
+  onError?: (err: unknown) => void;
+}
+/**
+ * Regenerates the schema and the env when the API schema changes (polling).
+ * Returns a function that stops the watcher.
+ */
+export declare function watchCodegen(options: WatchOptions): () => void;
+export { DEFAULT_ENV_FILE, DEFAULT_SCHEMA_FILE };
+//# sourceMappingURL=codegen.d.ts.map

package/dist/cli/codegen.js

@@ -0,0 +1,109 @@
+import { DEFAULT_ENV_FILE, DEFAULT_SCHEMA_FILE } from "../shared/constants.js";
+import fs from "node:fs";
+import path from "node:path";
+import { minifyIntrospection, preprocessIntrospection } from "@gql.tada/internal";
+import { buildClientSchema, getIntrospectionQuery, printSchema } from "graphql";
+// src/cli/codegen.ts
+/**
+* Introspects the PocketBomb GraphQL API (`POST /api/graphql`; the introspection
+* fields are not counted in the query limits).
+*
+* @throws {Error} for the HTTP and GraphQL errors.
+*/
+async function introspect(options) {
+	const headers = { "content-type": "application/json" };
+	if (options.publicKey) headers["X-PB-Public-Key"] = options.publicKey;
+	const endpoint = options.url.replace(/\/+$/, "") + "/api/graphql";
+	const response = await (options.fetch || fetch)(endpoint, {
+		method: "POST",
+		headers,
+		body: JSON.stringify({ query: getIntrospectionQuery({ descriptions: true }) })
+	});
+	let body = null;
+	try {
+		body = await response.json();
+	} catch {
+		body = null;
+	}
+	if (!response.ok) throw new Error(`The GraphQL introspection failed (${response.status}): ${body?.message || JSON.stringify(body)}`);
+	if (body?.errors?.length || !body?.data?.__schema) throw new Error("The GraphQL introspection failed: " + (body?.errors?.map((e) => e.message).join("; ") || "no schema"));
+	return body.data;
+}
+/**
+* Returns a copy of the introspection without the empty descriptions
+* (the server reports "" for the undocumented fields).
+*/
+function withoutEmptyDescriptions(value) {
+	if (Array.isArray(value)) return value.map(withoutEmptyDescriptions);
+	if (value && typeof value === "object") {
+		const result = {};
+		for (const [key, item] of Object.entries(value)) result[key] = key === "description" && item === "" ? null : withoutEmptyDescriptions(item);
+		return result;
+	}
+	return value;
+}
+/**
+* Returns the GraphQL SDL of an introspection.
+*/
+function introspectionToSDL(introspection) {
+	return printSchema(buildClientSchema(withoutEmptyDescriptions(introspection))) + "\n";
+}
+/**
+* Returns the `pocketbomb-env.d.ts` of an introspection: the gql.tada introspection type
+* and the `pocketbomb-dynamite/graphql` schema augmentation used by `graphql()`.
+*/
+function introspectionToEnv(introspection) {
+	return "/* eslint-disable */\n/* prettier-ignore */\n// Generated by `dynamite codegen` from the PocketBomb GraphQL API. Do not edit.\n\n/** The gql.tada introspection of the PocketBomb GraphQL schema. */\nexport type introspection = " + preprocessIntrospection(minifyIntrospection(introspection)) + ";\n\ndeclare module \"pocketbomb-dynamite/graphql\" {\n  interface PocketBombSchema {\n    introspection: introspection;\n  }\n}\n";
+}
+function writeIfChanged(file, content) {
+	if (fs.existsSync(file) && fs.readFileSync(file, "utf8") === content) return false;
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	fs.writeFileSync(file, content);
+	return true;
+}
+/**
+* Writes the schema SDL and the gql.tada env of an introspection (only if they changed).
+*/
+function generate(introspection, options = {}) {
+	const cwd = options.cwd || process.cwd();
+	const schemaFile = path.resolve(cwd, options.schemaFile || ".dynamite/schema.graphql");
+	const envFile = path.resolve(cwd, options.envFile || "pocketbomb-env.d.ts");
+	const schemaChanged = writeIfChanged(schemaFile, introspectionToSDL(introspection));
+	const envChanged = writeIfChanged(envFile, introspectionToEnv(introspection));
+	return {
+		schemaFile,
+		envFile,
+		changed: schemaChanged || envChanged
+	};
+}
+/**
+* Introspects the API and writes the schema and the env (see {@link generate}).
+*/
+async function codegen(options) {
+	return generate(await introspect(options), options);
+}
+/**
+* Regenerates the schema and the env when the API schema changes (polling).
+* Returns a function that stops the watcher.
+*/
+function watchCodegen(options) {
+	let stopped = false;
+	let timer;
+	const tick = async () => {
+		try {
+			const result = await codegen(options);
+			if (result.changed) options.onChange?.(result);
+		} catch (err) {
+			options.onError?.(err);
+		}
+		if (!stopped) timer = setTimeout(tick, options.interval ?? 2e3);
+	};
+	tick();
+	return () => {
+		stopped = true;
+		clearTimeout(timer);
+	};
+}
+export { DEFAULT_ENV_FILE, DEFAULT_SCHEMA_FILE, codegen, generate, introspect, introspectionToEnv, introspectionToSDL, watchCodegen, withoutEmptyDescriptions };
+
+//# sourceMappingURL=codegen.js.map

package/dist/cli/codegen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.js","names":[],"sources":["../../src/cli/codegen.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { minifyIntrospection, preprocessIntrospection } from \"@gql.tada/internal\";\nimport {\n  buildClientSchema,\n  getIntrospectionQuery,\n  printSchema,\n  type IntrospectionQuery,\n} from \"graphql\";\n\nimport { DEFAULT_ENV_FILE, DEFAULT_SCHEMA_FILE } from \"../shared/constants\";\n\nexport { DEFAULT_ENV_FILE, DEFAULT_SCHEMA_FILE };\n\nexport interface IntrospectOptions {\n  /** The PocketBomb URL. */\n  url: string;\n  /** The public API key (the GraphQL API requires client credentials). */\n  publicKey?: string;\n  fetch?: typeof fetch;\n}\n\n/**\n * Introspects the PocketBomb GraphQL API (`POST /api/graphql`; the introspection\n * fields are not counted in the query limits).\n *\n * @throws {Error} for the HTTP and GraphQL errors.\n */\nexport async function introspect(options: IntrospectOptions): Promise<IntrospectionQuery> {\n  const headers: Record<string, string> = { \"content-type\": \"application/json\" };\n  if (options.publicKey) {\n    headers[\"X-PB-Public-Key\"] = options.publicKey;\n  }\n\n  const endpoint = options.url.replace(/\\/+$/, \"\") + \"/api/graphql\";\n  const response = await (options.fetch || fetch)(endpoint, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify({ query: getIntrospectionQuery({ descriptions: true }) }),\n  });\n\n  let body: any = null;\n  try {\n    body = await response.json();\n  } catch {\n    body = null;\n  }\n\n  if (!response.ok) {\n    throw new Error(\n      `The GraphQL introspection failed (${response.status}): ${body?.message || JSON.stringify(body)}`,\n    );\n  }\n  if (body?.errors?.length || !body?.data?.__schema) {\n    throw new Error(\n      \"The GraphQL introspection failed: \" +\n        (body?.errors?.map((e: any) => e.message).join(\"; \") || \"no schema\"),\n    );\n  }\n\n  return body.data as IntrospectionQuery;\n}\n\n/**\n * Returns a copy of the introspection without the empty descriptions\n * (the server reports \"\" for the undocumented fields).\n */\nexport function withoutEmptyDescriptions<T>(value: T): T {\n  if (Array.isArray(value)) {\n    return value.map(withoutEmptyDescriptions) as T;\n  }\n\n  if (value && typeof value === \"object\") {\n    const result: Record<string, unknown> = {};\n    for (const [key, item] of Object.entries(value)) {\n      result[key] = key === \"description\" && item === \"\" ? null : withoutEmptyDescriptions(item);\n    }\n    return result as T;\n  }\n\n  return value;\n}\n\n/**\n * Returns the GraphQL SDL of an introspection.\n */\nexport function introspectionToSDL(introspection: IntrospectionQuery): string {\n  return printSchema(buildClientSchema(withoutEmptyDescriptions(introspection))) + \"\\n\";\n}\n\n/**\n * Returns the `pocketbomb-env.d.ts` of an introspection: the gql.tada introspection type\n * and the `pocketbomb-dynamite/graphql` schema augmentation used by `graphql()`.\n */\nexport function introspectionToEnv(introspection: IntrospectionQuery): string {\n  const type = preprocessIntrospection(minifyIntrospection(introspection));\n\n  return (\n    \"/* eslint-disable */\\n\" +\n    \"/* prettier-ignore */\\n\" +\n    \"// Generated by `dynamite codegen` from the PocketBomb GraphQL API. Do not edit.\\n\\n\" +\n    \"/** The gql.tada introspection of the PocketBomb GraphQL schema. */\\n\" +\n    \"export type introspection = \" +\n    type +\n    \";\\n\\n\" +\n    'declare module \"pocketbomb-dynamite/graphql\" {\\n' +\n    \"  interface PocketBombSchema {\\n\" +\n    \"    introspection: introspection;\\n\" +\n    \"  }\\n\" +\n    \"}\\n\"\n  );\n}\n\nexport interface GenerateOptions {\n  /** The project root (default to the current working dir). */\n  cwd?: string;\n  /** The SDL output (default to `.dynamite/schema.graphql`). */\n  schemaFile?: string;\n  /** The gql.tada env output (default to `pocketbomb-env.d.ts`). */\n  envFile?: string;\n}\n\nexport interface GenerateResult {\n  schemaFile: string;\n  envFile: string;\n  /** Whether a file was (re)written. */\n  changed: boolean;\n}\n\nfunction writeIfChanged(file: string, content: string): boolean {\n  if (fs.existsSync(file) && fs.readFileSync(file, \"utf8\") === content) {\n    return false;\n  }\n\n  fs.mkdirSync(path.dirname(file), { recursive: true });\n  fs.writeFileSync(file, content);\n\n  return true;\n}\n\n/**\n * Writes the schema SDL and the gql.tada env of an introspection (only if they changed).\n */\nexport function generate(\n  introspection: IntrospectionQuery,\n  options: GenerateOptions = {},\n): GenerateResult {\n  const cwd = options.cwd || process.cwd();\n  const schemaFile = path.resolve(cwd, options.schemaFile || DEFAULT_SCHEMA_FILE);\n  const envFile = path.resolve(cwd, options.envFile || DEFAULT_ENV_FILE);\n\n  const schemaChanged = writeIfChanged(schemaFile, introspectionToSDL(introspection));\n  const envChanged = writeIfChanged(envFile, introspectionToEnv(introspection));\n\n  return { schemaFile, envFile, changed: schemaChanged || envChanged };\n}\n\nexport interface CodegenOptions extends IntrospectOptions, GenerateOptions {}\n\n/**\n * Introspects the API and writes the schema and the env (see {@link generate}).\n */\nexport async function codegen(options: CodegenOptions): Promise<GenerateResult> {\n  return generate(await introspect(options), options);\n}\n\nexport interface WatchOptions extends CodegenOptions {\n  /** The schema poll interval in ms (default to 2000). */\n  interval?: number;\n  /** Called after every generation that changed a file. */\n  onChange?: (result: GenerateResult) => void;\n  /** Called for the failed polls (the watcher keeps running). */\n  onError?: (err: unknown) => void;\n}\n\n/**\n * Regenerates the schema and the env when the API schema changes (polling).\n * Returns a function that stops the watcher.\n */\nexport function watchCodegen(options: WatchOptions): () => void {\n  let stopped = false;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n\n  const tick = async () => {\n    try {\n      const result = await codegen(options);\n      if (result.changed) {\n        options.onChange?.(result);\n      }\n    } catch (err) {\n      options.onError?.(err);\n    }\n\n    if (!stopped) {\n      timer = setTimeout(tick, options.interval ?? 2000);\n    }\n  };\n\n  void tick();\n\n  return () => {\n    stopped = true;\n    clearTimeout(timer);\n  };\n}\n"],"mappings":";;;;;;;;;;;;AA4BA,eAAsB,WAAW,SAAyD;CACxF,MAAM,UAAkC,EAAE,gBAAgB,mBAAmB;CAC7E,IAAI,QAAQ,WACV,QAAQ,qBAAqB,QAAQ;CAGvC,MAAM,WAAW,QAAQ,IAAI,QAAQ,QAAQ,EAAE,IAAI;CACnD,MAAM,WAAW,OAAO,QAAQ,SAAS,MAAA,CAAO,UAAU;EACxD,QAAQ;EACR;EACA,MAAM,KAAK,UAAU,EAAE,OAAO,sBAAsB,EAAE,cAAc,KAAK,CAAC,EAAE,CAAC;CAC/E,CAAC;CAED,IAAI,OAAY;CAChB,IAAI;EACF,OAAO,MAAM,SAAS,KAAK;CAC7B,QAAQ;EACN,OAAO;CACT;CAEA,IAAI,CAAC,SAAS,IACZ,MAAM,IAAI,MACR,qCAAqC,SAAS,OAAO,KAAK,MAAM,WAAW,KAAK,UAAU,IAAI,GAChG;CAEF,IAAI,MAAM,QAAQ,UAAU,CAAC,MAAM,MAAM,UACvC,MAAM,IAAI,MACR,wCACG,MAAM,QAAQ,KAAK,MAAW,EAAE,OAAO,CAAC,CAAC,KAAK,IAAI,KAAK,YAC5D;CAGF,OAAO,KAAK;AACd;;;;;AAMA,SAAgB,yBAA4B,OAAa;CACvD,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,IAAI,wBAAwB;CAG3C,IAAI,SAAS,OAAO,UAAU,UAAU;EACtC,MAAM,SAAkC,CAAC;EACzC,KAAK,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,KAAK,GAC5C,OAAO,OAAO,QAAQ,iBAAiB,SAAS,KAAK,OAAO,yBAAyB,IAAI;EAE3F,OAAO;CACT;CAEA,OAAO;AACT;;;;AAKA,SAAgB,mBAAmB,eAA2C;CAC5E,OAAO,YAAY,kBAAkB,yBAAyB,aAAa,CAAC,CAAC,IAAI;AACnF;;;;;AAMA,SAAgB,mBAAmB,eAA2C;CAG5E,OACE,uOAHW,wBAAwB,oBAAoB,aAAa,CAQjE,IACH;AAOJ;AAkBA,SAAS,eAAe,MAAc,SAA0B;CAC9D,IAAI,GAAG,WAAW,IAAI,KAAK,GAAG,aAAa,MAAM,MAAM,MAAM,SAC3D,OAAO;CAGT,GAAG,UAAU,KAAK,QAAQ,IAAI,GAAG,EAAE,WAAW,KAAK,CAAC;CACpD,GAAG,cAAc,MAAM,OAAO;CAE9B,OAAO;AACT;;;;AAKA,SAAgB,SACd,eACA,UAA2B,CAAC,GACZ;CAChB,MAAM,MAAM,QAAQ,OAAO,QAAQ,IAAI;CACvC,MAAM,aAAa,KAAK,QAAQ,KAAK,QAAQ,cAAA,0BAAiC;CAC9E,MAAM,UAAU,KAAK,QAAQ,KAAK,QAAQ,WAAA,qBAA2B;CAErE,MAAM,gBAAgB,eAAe,YAAY,mBAAmB,aAAa,CAAC;CAClF,MAAM,aAAa,eAAe,SAAS,mBAAmB,aAAa,CAAC;CAE5E,OAAO;EAAE;EAAY;EAAS,SAAS,iBAAiB;CAAW;AACrE;;;;AAOA,eAAsB,QAAQ,SAAkD;CAC9E,OAAO,SAAS,MAAM,WAAW,OAAO,GAAG,OAAO;AACpD;;;;;AAeA,SAAgB,aAAa,SAAmC;CAC9D,IAAI,UAAU;CACd,IAAI;CAEJ,MAAM,OAAO,YAAY;EACvB,IAAI;GACF,MAAM,SAAS,MAAM,QAAQ,OAAO;GACpC,IAAI,OAAO,SACT,QAAQ,WAAW,MAAM;EAE7B,SAAS,KAAK;GACZ,QAAQ,UAAU,GAAG;EACvB;EAEA,IAAI,CAAC,SACH,QAAQ,WAAW,MAAM,QAAQ,YAAY,GAAI;CAErD;CAEA,KAAU;CAEV,aAAa;EACX,UAAU;EACV,aAAa,KAAK;CACpB;AACF"}