@yaakdoc/snippets 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 József Sallai
+
+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,44 @@
-# Temporary Holding Version
+# @yaakdoc/snippets
 
-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.
+Code example generators for [yaakdoc](https://github.com/jozsefsallai/yaakdoc#readme).
+
+| Id | Language | Request kinds |
+| --- | --- | --- |
+| `curl` | bash | HTTP |
+| `javascript` | JavaScript (`fetch`, `WebSocket`) | HTTP, WebSocket |
+| `python` | Python (`requests`) | HTTP |
+| `go` | Go (`net/http`) | HTTP |
+| `grpcurl` | bash | gRPC |
+| `wscat` | bash | WebSocket |
+
+The generators handle JSON, text, form, multipart, GraphQL and binary bodies, headers, path and query parameters, and authentication: basic, bearer, API key (header or query), plus placeholders for OAuth and JWT.
+
+## Custom snippets
+
+```ts
+// snippets/httpie.ts
+import { applyAuth } from "@yaakdoc/core";
+import { defineSnippet } from "@yaakdoc/snippets";
+
+export default defineSnippet({
+  id: "httpie",
+  label: "HTTPie",
+  language: "bash",
+  supports: ["http"],
+  generate(request) {
+    if (request.kind !== "http") {
+      return "";
+    }
+
+    const req = applyAuth(request);
+
+    return [`http ${req.method} '${req.url}'`, ...req.headers.map((h) => `'${h.name}:${h.value}'`)].join(" \\\n  ");
+  },
+});
+```
+
+```json
+{ "snippets": ["curl", "./snippets/httpie.ts", "python"] }
+```
+
+The order of `snippets` is the order of the tabs. Use `generateExamples(resolvedRequest, snippets)` to generate examples programmatically.

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+import { RequestKind, ResolvedRequest } from "@yaakdoc/core";
+//#region src/generators/curl.d.ts
+export declare const curl: Snippet;
+//#endregion
+//#region src/generators/go.d.ts
+export declare const go: Snippet;
+//#endregion
+//#region src/generators/grpcurl.d.ts
+export declare const grpcurl: Snippet;
+//#endregion
+//#region src/generators/javascript.d.ts
+export declare const javascript: Snippet;
+//#endregion
+//#region src/generators/python.d.ts
+/** Serializes a JSON value as a Python literal. */
+export declare function toPython(value: unknown, level?: number): string;
+export declare const python: Snippet;
+//#endregion
+//#region src/generators/wscat.d.ts
+export declare const wscat: Snippet;
+//#endregion
+//#region src/types.d.ts
+type Snippet = {
+  /** Unique id, referenced from `snippets` in the yaakdoc config. */
+  id: string;
+  /** Human readable label, e.g. "cURL". */
+  label: string;
+  /** Shiki language id used for syntax highlighting. */
+  language: string;
+  /** Request kinds this snippet can generate code for. */
+  supports: readonly RequestKind[];
+  generate(request: ResolvedRequest): string;
+};
+type GeneratedExample = {
+  id: string;
+  label: string;
+  language: string;
+  code: string;
+};
+//#endregion
+//#region src/define.d.ts
+/** Defines a code example generator. Identity function for type inference. */
+export declare function defineSnippet(snippet: Snippet): Snippet;
+//#endregion
+//#region src/index.d.ts
+export declare const builtinSnippets: Readonly<Record<string, Snippet>>;
+/** Generates code examples for a request with every applicable snippet. */
+export declare function generateExamples(request: ResolvedRequest, snippets: readonly Snippet[]): GeneratedExample[];
+//#endregion
+export type { GeneratedExample, Snippet };

package/dist/index.js

@@ -0,0 +1,492 @@
+import { applyAuth, grpcMethodPath, tryParseJson } from "@yaakdoc/core";
+//#region src/define.ts
+/** Defines a code example generator. Identity function for type inference. */
+function defineSnippet(snippet) {
+	return snippet;
+}
+//#endregion
+//#region src/utils.ts
+/** Quotes a string for POSIX shells using single quotes. */
+function shellQuote(value) {
+	if (value !== "" && /^[\w@%+=:,./-]+$/.test(value)) return value;
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** Returns the content type implied by a body, if any. */
+function bodyContentType(body) {
+	return body.type === "none" || body.type === "multipart" ? null : body.contentType;
+}
+/** Adds a Content-Type header for the body unless one is already present. */
+function withContentType(headers, body) {
+	const contentType = bodyContentType(body);
+	if (!contentType || headers.some((h) => h.name.toLowerCase() === "content-type")) return headers;
+	return [...headers, {
+		name: "Content-Type",
+		value: contentType
+	}];
+}
+/** GraphQL bodies are sent as JSON `{ query, variables, operationName }`. */
+function graphqlPayload(body, query = graphqlQuery(body)) {
+	const variables = graphqlVariables(body);
+	return {
+		query,
+		...variables !== void 0 ? { variables } : {},
+		...body.operationName ? { operationName: body.operationName } : {}
+	};
+}
+/** Variables as a value (parsed JSON), the raw text when it isn't JSON, or `undefined`. */
+function graphqlVariables(body) {
+	if (!body.variables?.trim()) return;
+	const parsed = tryParseJson(body.variables);
+	return parsed.ok ? parsed.value : body.variables;
+}
+/** The query with common indentation and surrounding blank lines removed. */
+function graphqlQuery(body) {
+	const lines = body.query.replace(/\r\n?/g, "\n").split("\n");
+	while (lines.length > 0 && lines[0].trim() === "") lines.shift();
+	while (lines.length > 0 && lines.at(-1).trim() === "") lines.pop();
+	const indents = lines.filter((line) => line.trim()).map((line) => line.match(/^\s*/)[0].length);
+	const common = indents.length > 0 ? Math.min(...indents) : 0;
+	return lines.map((line) => line.slice(common).trimEnd()).join("\n");
+}
+/**
+* Collapses a GraphQL document onto one readable line (for JSON bodies in shell commands):
+* comments are removed and whitespace outside strings is collapsed, e.g.
+* `mutation x($id: ID!) { node(id: $id) { id } }`.
+*/
+function minifyGraphql(query) {
+	let out = "";
+	let inString = false;
+	for (let i = 0; i < query.length; i++) {
+		const char = query[i];
+		if (inString) {
+			out += char;
+			if (char === "\\") out += query[++i] ?? "";
+			else if (char === "\"") inString = false;
+		} else if (char === "#") while (i + 1 < query.length && query[i + 1] !== "\n") i++;
+		else if (/\s/.test(char)) {
+			if (!out.endsWith(" ")) out += " ";
+		} else {
+			if (char === "\"") inString = true;
+			out += char;
+		}
+	}
+	return out.replace(/\( /g, "(").replace(/ \)/g, ")").trim();
+}
+/** Body as a single string, for bodies that can be represented as one. */
+function bodyText(body) {
+	switch (body.type) {
+		case "json":
+		case "text": return body.text;
+		case "form-urlencoded": return body.fields.map((field) => `${encodeURIComponent(field.name)}=${encodeURIComponent(field.value)}`).join("&");
+		default: return null;
+	}
+}
+function indent(text, prefix) {
+	return text.split("\n").map((line, index) => index === 0 ? line : prefix + line).join("\n");
+}
+/** Prefixes every non-empty line. */
+function indentLines(text, prefix) {
+	return text.split("\n").map((line) => line ? prefix + line : line).join("\n");
+}
+//#endregion
+//#region src/generators/curl.ts
+const curl = defineSnippet({
+	id: "curl",
+	label: "cURL",
+	language: "bash",
+	supports: ["http"],
+	generate(request) {
+		if (request.kind !== "http") return "";
+		const basic = request.auth?.type === "basic" ? request.auth : null;
+		const req = basic ? {
+			...request,
+			auth: null
+		} : applyAuth(request);
+		const parts = [];
+		parts.push(req.method === "GET" && req.body.type === "none" ? `curl ${shellQuote(req.url)}` : `curl -X ${req.method} ${shellQuote(req.url)}`);
+		for (const header of withContentType(req.headers, req.body)) parts.push(`-H ${shellQuote(`${header.name}: ${header.value}`)}`);
+		if (basic) parts.push(`-u ${shellQuote(`${basic.username}:${basic.password}`)}`);
+		const { body } = req;
+		switch (body.type) {
+			case "json":
+			case "text":
+				if (body.text) parts.push(`--data-raw ${shellQuote(body.text)}`);
+				break;
+			case "graphql": {
+				const payload = graphqlPayload(body, minifyGraphql(graphqlQuery(body)));
+				parts.push(`--data-raw ${shellQuote(JSON.stringify(payload, null, 2))}`);
+				break;
+			}
+			case "form-urlencoded":
+				for (const field of body.fields) parts.push(`--data-urlencode ${shellQuote(`${field.name}=${field.value}`)}`);
+				break;
+			case "multipart":
+				for (const field of body.fields) {
+					const value = field.file ? `@${field.file}${field.contentType ? `;type=${field.contentType}` : ""}` : field.value;
+					parts.push(`-F ${shellQuote(`${field.name}=${value}`)}`);
+				}
+				break;
+			case "binary": parts.push(`--data-binary ${shellQuote(`@${body.filePath ?? "file"}`)}`);
+		}
+		return parts.join(" \\\n  ");
+	}
+});
+//#endregion
+//#region src/generators/go.ts
+const goStr = (value) => value.includes("`") || !value.includes("\n") ? JSON.stringify(value) : `\`${value}\``;
+const go = defineSnippet({
+	id: "go",
+	label: "Go",
+	language: "go",
+	supports: ["http"],
+	generate(request) {
+		if (request.kind !== "http") return "";
+		const basic = request.auth?.type === "basic" ? request.auth : null;
+		const req = basic ? {
+			...request,
+			auth: null
+		} : applyAuth(request);
+		const imports = /* @__PURE__ */ new Set([
+			"fmt",
+			"io",
+			"net/http"
+		]);
+		const setup = [];
+		let bodyVar = "nil";
+		const headers = withContentType(req.headers, req.body);
+		const { body } = req;
+		if (body.type === "multipart") {
+			imports.add("bytes");
+			imports.add("mime/multipart");
+			setup.push("	body := &bytes.Buffer{}", "	writer := multipart.NewWriter(body)");
+			for (const field of body.fields) if (field.file) {
+				imports.add("os");
+				setup.push(`\tfile, _ := os.Open(${goStr(field.file)})`, "	defer file.Close()", `\tpart, _ := writer.CreateFormFile(${goStr(field.name)}, ${goStr(field.file.split("/").at(-1) ?? field.file)})`, "	io.Copy(part, file)");
+			} else setup.push(`\twriter.WriteField(${goStr(field.name)}, ${goStr(field.value)})`);
+			setup.push("	writer.Close()", "");
+			bodyVar = "body";
+			headers.push({
+				name: "Content-Type",
+				value: "__MULTIPART__"
+			});
+		} else if (body.type === "binary") {
+			imports.add("os");
+			setup.push(`\tbody, _ := os.Open(${goStr(body.filePath ?? "file")})`, "	defer body.Close()", "");
+			bodyVar = "body";
+		} else if (body.type === "graphql") {
+			imports.add("bytes");
+			imports.add("encoding/json");
+			const query = graphqlQuery(body);
+			const variables = graphqlVariables(body);
+			const fields = [["query", "query"]];
+			setup.push(query.includes("`") ? `\tquery := ${JSON.stringify(query)}` : `\tquery := \`\n${indentLines(query, "		")}\n\t\``);
+			if (variables !== void 0) {
+				const json = JSON.stringify(variables, null, "	");
+				setup.push(json.includes("`") ? `\tvariables := json.RawMessage(${JSON.stringify(json)})` : `\tvariables := json.RawMessage(\`${indent(json, "	")}\`)`);
+				fields.push(["variables", "variables"]);
+			}
+			if (body.operationName) fields.push(["operationName", goStr(body.operationName)]);
+			const width = Math.max(...fields.map(([key]) => key.length)) + 3;
+			setup.push("", "	payload, _ := json.Marshal(map[string]any{", ...fields.map(([key, value]) => `\t\t${`"${key}":`.padEnd(width)} ${value},`), "	})", "");
+			bodyVar = "bytes.NewReader(payload)";
+		} else {
+			const text = bodyText(body);
+			if (text) {
+				imports.add("strings");
+				setup.push(`\tbody := strings.NewReader(${goStr(text)})`, "");
+				bodyVar = "body";
+			}
+		}
+		return [
+			"package main",
+			"",
+			`import (\n${[...imports].sort().map((i) => `\t"${i}"`).join("\n")}\n)`,
+			"",
+			"func main() {",
+			...setup,
+			`\treq, err := http.NewRequest(${goStr(req.method)}, ${goStr(req.url)}, ${bodyVar})`,
+			"	if err != nil {",
+			"		panic(err)",
+			"	}",
+			...headers.map((h) => h.value === "__MULTIPART__" ? "	req.Header.Set(\"Content-Type\", writer.FormDataContentType())" : `\treq.Header.Set(${goStr(h.name)}, ${goStr(h.value)})`),
+			...basic ? [`\treq.SetBasicAuth(${goStr(basic.username)}, ${goStr(basic.password)})`] : [],
+			"",
+			"	res, err := http.DefaultClient.Do(req)",
+			"	if err != nil {",
+			"		panic(err)",
+			"	}",
+			"	defer res.Body.Close()",
+			"",
+			"	data, _ := io.ReadAll(res.Body)",
+			"	fmt.Println(string(data))",
+			"}"
+		].join("\n");
+	}
+});
+//#endregion
+//#region src/generators/grpcurl.ts
+const grpcurl = defineSnippet({
+	id: "grpcurl",
+	label: "grpcurl",
+	language: "bash",
+	supports: ["grpc"],
+	generate(request) {
+		if (request.kind !== "grpc") return "";
+		const plaintext = request.url.startsWith("http://") || request.url.startsWith("grpc://");
+		const address = request.url.replace(/^[a-z]+:\/\//i, "").replace(/\/+$/, "") || "localhost:443";
+		const parts = ["grpcurl"];
+		if (plaintext) parts.push("-plaintext");
+		const metadata = [...request.metadata];
+		const { auth } = request;
+		if (auth?.type === "bearer") metadata.push({
+			name: "authorization",
+			value: `${auth.prefix} ${auth.token}`
+		});
+		else if (auth?.type === "apikey") metadata.push({
+			name: auth.key,
+			value: auth.value
+		});
+		else if (auth?.type === "other" && auth.header) metadata.push(auth.header);
+		for (const entry of metadata) parts.push(`-H ${shellQuote(`${entry.name}: ${entry.value}`)}`);
+		if (request.message.trim()) parts.push(`-d ${shellQuote(request.message.trim())}`);
+		parts.push(address);
+		const method = grpcMethodPath(request);
+		if (method) parts.push(method);
+		return parts.join(" \\\n  ");
+	}
+});
+//#endregion
+//#region src/generators/javascript.ts
+const str = (value) => JSON.stringify(value);
+const objectLiteral = (entries, pad) => entries.length === 0 ? "{}" : `{\n${entries.map(([k, v]) => `${pad}  ${str(k)}: ${str(v)},`).join("\n")}\n${pad}}`;
+const javascript = defineSnippet({
+	id: "javascript",
+	label: "JavaScript",
+	language: "javascript",
+	supports: ["http", "websocket"],
+	generate(request) {
+		if (request.kind === "websocket") {
+			const req = applyAuth(request);
+			const lines = [`const socket = new WebSocket(${str(req.url)});`, ""];
+			if (req.headers.length > 0) lines.unshift("// Note: browsers don't support custom WebSocket headers. In Node.js, use the `ws` package:", `// new WebSocket(url, { headers: ${JSON.stringify(Object.fromEntries(req.headers.map((h) => [h.name, h.value])))} })`);
+			lines.push("socket.addEventListener(\"open\", () => {", req.message ? `  socket.send(${templateString(req.message)});` : "  // Connected", "});", "", "socket.addEventListener(\"message\", (event) => {", "  console.log(event.data);", "});");
+			return lines.join("\n");
+		}
+		if (request.kind !== "http") return "";
+		if (request.auth?.type === "basic") {
+			const { username, password } = request.auth;
+			const credentials = str(`${username}:${password}`);
+			return fetchSnippet({
+				...request,
+				auth: null
+			}, credentials);
+		}
+		return fetchSnippet(applyAuth(request));
+	}
+});
+function fetchSnippet(req, basicCredentials) {
+	const pre = [];
+	const options = [];
+	const headerEntries = withContentType(req.headers, req.body).map((h) => `    ${str(h.name)}: ${str(h.value)},`);
+	if (basicCredentials) headerEntries.push(`    Authorization: \`Basic \${btoa(${basicCredentials})}\`,`);
+	if (req.method !== "GET") options.push(`method: ${str(req.method)},`);
+	if (headerEntries.length > 0) options.push(`headers: {\n${headerEntries.join("\n")}\n  },`);
+	const { body } = req;
+	switch (body.type) {
+		case "json": {
+			const parsed = tryParseJson(body.text);
+			if (parsed.ok) options.push(`body: JSON.stringify(${indent(JSON.stringify(parsed.value, null, 2), "  ")}),`);
+			else if (body.text) options.push(`body: ${templateString(body.text)},`);
+			break;
+		}
+		case "text":
+			if (body.text) options.push(`body: ${templateString(body.text)},`);
+			break;
+		case "graphql": {
+			pre.push(`const query = /* GraphQL */ \`\n${indentLines(escapeTemplate(graphqlQuery(body)), "  ")}\n\`;`, "");
+			const variables = graphqlVariables(body);
+			const fields = [
+				"    query,",
+				...variables !== void 0 ? [`    variables: ${indent(JSON.stringify(variables, null, 2), "    ")},`] : [],
+				...body.operationName ? [`    operationName: ${str(body.operationName)},`] : []
+			];
+			options.push(`body: JSON.stringify({\n${fields.join("\n")}\n  }),`);
+			break;
+		}
+		case "form-urlencoded":
+			options.push(`body: new URLSearchParams(${objectLiteral(body.fields.map((f) => [f.name, f.value]), "  ")}),`);
+			break;
+		case "multipart":
+			pre.push("const form = new FormData();");
+			for (const field of body.fields) pre.push(field.file ? `form.append(${str(field.name)}, fileInput.files[0]); // ${field.file}` : `form.append(${str(field.name)}, ${str(field.value)});`);
+			pre.push("");
+			options.push("body: form,");
+			break;
+		case "binary": options.push(`body: file, // ${body.filePath ?? "binary file"}`);
+	}
+	const call = options.length === 0 ? `const response = await fetch(${str(req.url)});` : `const response = await fetch(${str(req.url)}, {\n${options.map((o) => `  ${o}`).join("\n")}\n});`;
+	return [
+		...pre,
+		call,
+		"",
+		"const data = await response.json();",
+		"console.log(data);"
+	].join("\n");
+}
+function templateString(value) {
+	if (!value.includes("\n")) return str(value);
+	return `\`${escapeTemplate(value)}\``;
+}
+/** Escapes text for a JavaScript template literal. */
+function escapeTemplate(value) {
+	return value.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+}
+//#endregion
+//#region src/generators/python.ts
+const pyStr = (value) => JSON.stringify(value);
+/** Serializes a JSON value as a Python literal. */
+function toPython(value, level = 0) {
+	const pad = "    ".repeat(level);
+	const inner = "    ".repeat(level + 1);
+	if (value === null || value === void 0) return "None";
+	if (value === true) return "True";
+	if (value === false) return "False";
+	if (typeof value === "number") return String(value);
+	if (typeof value === "string") return pyStr(value);
+	if (Array.isArray(value)) {
+		if (value.length === 0) return "[]";
+		return `[\n${value.map((item) => `${inner}${toPython(item, level + 1)},`).join("\n")}\n${pad}]`;
+	}
+	const entries = Object.entries(value);
+	if (entries.length === 0) return "{}";
+	return `{\n${entries.map(([k, v]) => `${inner}${pyStr(k)}: ${toPython(v, level + 1)},`).join("\n")}\n${pad}}`;
+}
+const python = defineSnippet({
+	id: "python",
+	label: "Python",
+	language: "python",
+	supports: ["http"],
+	generate(request) {
+		if (request.kind !== "http") return "";
+		const basic = request.auth?.type === "basic" ? request.auth : null;
+		const req = basic ? {
+			...request,
+			auth: null
+		} : applyAuth(request);
+		const lines = [
+			"import requests",
+			"",
+			`url = ${pyStr(req.url)}`
+		];
+		const args = ["url"];
+		const { body } = req;
+		const headers = withContentType(req.headers, body).filter((h) => !((body.type === "json" || body.type === "graphql") && h.name.toLowerCase() === "content-type" && h.value === "application/json"));
+		if (headers.length > 0) {
+			lines.push(`headers = ${toPython(Object.fromEntries(headers.map((h) => [h.name, h.value])))}`);
+			args.push("headers=headers");
+		}
+		switch (body.type) {
+			case "json": {
+				const parsed = tryParseJson(body.text);
+				if (parsed.ok) {
+					lines.push(`payload = ${toPython(parsed.value)}`);
+					args.push("json=payload");
+				} else if (body.text) {
+					lines.push(`payload = ${pyStr(body.text)}`);
+					args.push("data=payload");
+				}
+				break;
+			}
+			case "graphql": {
+				const variables = graphqlVariables(body);
+				const query = graphqlQuery(body).replace(/\\/g, "\\\\").replace(/"""/g, "\\\"\\\"\\\"");
+				lines.push("", `query = """\n${query}\n"""`, "", [
+					"payload = {",
+					"    \"query\": query,",
+					...variables !== void 0 ? [`    "variables": ${toPython(variables, 1)},`] : [],
+					...body.operationName ? [`    "operationName": ${pyStr(body.operationName)},`] : [],
+					"}"
+				].join("\n"));
+				args.push("json=payload");
+				break;
+			}
+			case "text":
+				if (body.text) {
+					lines.push(`payload = ${pyStr(body.text)}`);
+					args.push("data=payload");
+				}
+				break;
+			case "form-urlencoded":
+				lines.push(`payload = ${toPython(Object.fromEntries(body.fields.map((f) => [f.name, f.value])))}`);
+				args.push("data=payload");
+				break;
+			case "multipart": {
+				const files = body.fields.filter((f) => f.file);
+				const data = body.fields.filter((f) => !f.file);
+				if (data.length > 0) {
+					lines.push(`payload = ${toPython(Object.fromEntries(data.map((f) => [f.name, f.value])))}`);
+					args.push("data=payload");
+				}
+				if (files.length > 0) {
+					lines.push(`files = {\n${files.map((f) => `    ${pyStr(f.name)}: open(${pyStr(f.file)}, "rb"),`).join("\n")}\n}`);
+					args.push("files=files");
+				}
+				break;
+			}
+			case "binary":
+				lines.push(`payload = open(${pyStr(body.filePath ?? "file")}, "rb")`);
+				args.push("data=payload");
+		}
+		if (basic) args.push(`auth=(${pyStr(basic.username)}, ${pyStr(basic.password)})`);
+		const method = req.method.toLowerCase();
+		const call = [
+			"get",
+			"post",
+			"put",
+			"patch",
+			"delete",
+			"head",
+			"options"
+		].includes(method) ? `requests.${method}(${args.join(", ")})` : `requests.request(${pyStr(req.method)}, ${args.join(", ")})`;
+		lines.push("", `response = ${call}`, "print(response.json())");
+		return lines.join("\n");
+	}
+});
+//#endregion
+//#region src/generators/wscat.ts
+const wscat = defineSnippet({
+	id: "wscat",
+	label: "wscat",
+	language: "bash",
+	supports: ["websocket"],
+	generate(request) {
+		if (request.kind !== "websocket") return "";
+		const req = applyAuth(request);
+		const parts = [`wscat -c ${shellQuote(req.url)}`];
+		for (const header of req.headers) parts.push(`-H ${shellQuote(`${header.name}: ${header.value}`)}`);
+		const command = parts.join(" \\\n  ");
+		if (!req.message) return command;
+		return `${command}\n\n# Then send:\n# ${req.message.split("\n").join("\n# ")}`;
+	}
+});
+//#endregion
+//#region src/index.ts
+const builtinSnippets = Object.freeze({
+	curl,
+	javascript,
+	python,
+	go,
+	grpcurl,
+	wscat
+});
+/** Generates code examples for a request with every applicable snippet. */
+function generateExamples(request, snippets) {
+	return snippets.filter((snippet) => snippet.supports.includes(request.kind)).map((snippet) => ({
+		id: snippet.id,
+		label: snippet.label,
+		language: snippet.language,
+		code: snippet.generate(request)
+	})).filter((example) => example.code.trim() !== "");
+}
+//#endregion
+export { builtinSnippets, curl, defineSnippet, generateExamples, go, grpcurl, javascript, python, toPython, wscat };

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@yaakdoc/snippets",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Code example generators (cURL, fetch, Python, Go, grpcurl, wscat) for yaakdoc.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "@yaakdoc/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "yaak",
+    "yaakdoc",
+    "code",
+    "snippets",
+    "curl",
+    "examples"
+  ],
+  "author": "József Sallai @jozsefsallai",
+  "license": "MIT",
+  "files": [
+    "/dist",
+    "/README.md",
+    "/LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jozsefsallai/yaakdoc.git",
+    "directory": "packages/snippets"
+  },
+  "bugs": {
+    "url": "https://github.com/jozsefsallai/yaakdoc/issues"
+  },
+  "homepage": "https://github.com/jozsefsallai/yaakdoc#readme",
+  "engines": {
+    "node": ">=20.19"
+  },
+  "devDependencies": {
+    "@repo/tsconfig": "0.0.0"
+  },
+  "dependencies": {
+    "@yaakdoc/core": "^0.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch --no-clean",
+    "test": "vitest run",
+    "check-types": "tsc",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint . --write",
+    "format": "biome format . --write"
+  }
 }