@lukoweb/apitogo 0.2.50 → 0.2.51

package/dist/cli/cli.js

@@ -6268,7 +6268,7 @@ title: Welcome
 
 # ${name}
 
-This page was created by \`apitogo init\`. Edit it, and add more \`.md\` or \`.mdx\` files next to it: each one becomes a page of your portal.
+Welcome to the ${name} developer portal. Here you will find guides, the API reference, and everything you need to get an API key and make your first call.
 `;
 }
 async function docsFromPaths(dir, requested) {
@@ -7657,7 +7657,8 @@ async function removeServicesFromManifest(state, names) {
 // src/config/v2/gateway-reference.ts
 import { readFile as readFile6 } from "node:fs/promises";
 import { parse } from "yaml";
-var DEFAULT_KEY_HEADER = "Ocp-Apim-Subscription-Key";
+var DEFAULT_KEY_HEADER = "X-API-Key";
+var KEY_HEADER_EXTENSION = "x-apitogo-key-header";
 var METHODS = [
   "get",
   "put",
@@ -7770,10 +7771,13 @@ function buildReferenceSpec(specText, options) {
   if (Object.keys(components).length > 0) doc.components = components;
   else delete doc.components;
   doc.security = Object.keys(requirement).length > 0 ? [requirement] : [];
-  for (const [, item, method] of operationsOf(paths)) {
+  for (const [path97, item, method] of operationsOf(paths)) {
     const operation = item[method];
     if (Array.isArray(operation.security) && operation.security.length > 0)
       delete operation.security;
+    if (options.apiKeyRequired && !options.publicOperations.has(actionKey(method, path97)))
+      operation[KEY_HEADER_EXTENSION] = options.apiKeyHeader;
+    else delete operation[KEY_HEADER_EXTENSION];
   }
   return JSON.parse(hideOrigin(JSON.stringify(doc), options));
 }
@@ -8089,6 +8093,8 @@ function planPortal(profile, manifest) {
       apiBaseUrl: plans.apiBaseUrl,
       keysApiBaseUrl: plans.keysApiBaseUrl,
       billing: plans.billing,
+      ...gateway?.keyHeaderName ? { keyHeader: gateway.keyHeaderName } : {},
+      ...gateway?.baseUrl && serviceReady(gateway) ? { gatewayBaseUrl: gateway.baseUrl } : {},
       links: {
         // Hosted docs are linked once their pages are known (see `buildPortalWorkspace`): there is no page to
         // name before that, and a guessed one was a 404 on every portal whose first page is not called `introduction`.
@@ -8630,7 +8636,7 @@ var FULL_SPEC = (name) => `openapi: 3.1.0
 info:
   title: ${JSON.stringify(name)}
   version: 1.0.0
-  description: A small sample API. Edit server/index.js and this file together.
+  description: A sample API with a greeting and a list of items.
 paths:
   /health:
     get:
@@ -8719,10 +8725,14 @@ components:
 // src/config/v2/starter-landing.ts
 function starterLandingPage(options) {
   const name = JSON.stringify(options.name);
-  const plansImport = options.withPlans ? 'import { usePlansPreview } from "@lukoweb/apitogo-plugin-dev-portal-billing";\n' : "";
-  const plansHook = options.withPlans ? "  // The plans of the project's catalog: the same ones the pricing page shows.\n  const plans = usePlansPreview();\n\n" : "";
+  const plansImport = options.withPlans ? 'import {\n  useGatewayCall,\n  usePlansPreview,\n} from "@lukoweb/apitogo-plugin-dev-portal-billing";\n' : "";
+  const plansHook = options.withPlans ? "  // The plans of the project's catalog: the same ones the pricing page shows.\n  const plans = usePlansPreview();\n  // The real gateway address and key header, so the sample works when it is pasted with a key.\n  const gateway = useGatewayCall();\n\n" : "";
+  const sampleUrl = options.withPlans ? '${gateway.baseUrl ?? "https://YOUR-GATEWAY"}' : "https://YOUR-GATEWAY";
+  const sampleHeader = options.withPlans ? "${gateway.keyHeader}" : "X-API-Key";
   const plansSection = options.withPlans ? "      <PlansPreviewSection plans={plans} />\n" : "";
-  return `import {
+  return `// Your portal's home page. Edit this file (apitogo/portal/landing/LandingPage.tsx) to make it yours: everything
+// on it is public, so keep notes for yourself in comments like this one.
+import {
   ApiShowcaseSection,
   FeaturesSection,
   HeroSection,
@@ -8752,8 +8762,8 @@ ${plansHook}  return (
           {
             filename: "Call the API",
             language: "bash",
-            code: \`$ curl https://your-api.example.com/health \\\\
-  -H "x-api-key: YOUR_API_KEY"
+            code: \`$ curl ${sampleUrl}/health \\\\
+  -H "${sampleHeader}: YOUR_API_KEY"
 # { "status": "ok" }\`,
           },
         ]}
@@ -8763,7 +8773,7 @@ ${plansHook}  return (
           label: "What you get",
           title: "A developer portal that is ready on day one",
           description:
-            "Edit this page in apitogo/portal/landing/LandingPage.tsx to make it yours.",
+            "Docs, a live API reference, self-service API keys and clear plans, all in one place.",
         }}
         features={[
           {
@@ -10771,7 +10781,7 @@ import {
 // package.json
 var package_default = {
   name: "@lukoweb/apitogo",
-  version: "0.2.50",
+  version: "0.2.51",
   type: "module",
   sideEffects: [
     "**/*.css",
@@ -16080,7 +16090,7 @@ async function onlinePlansRules(resolved, projectId, api) {
     const convert = (item) => issue3(
       "PLANS_PLAN_INVALID",
       `plans.file ${item.field}`,
-      `${item.sku ? `plan ${item.sku}: ` : ""}${item.message}`
+      withPlanName(item.message, item.sku)
     );
     return {
       errors: answer.errors.map(convert),
@@ -16094,6 +16104,7 @@ async function onlinePlansRules(resolved, projectId, api) {
     };
   }
 }
+var withPlanName = (message, sku) => !sku || message.toLowerCase().startsWith(`plan "${sku.toLowerCase()}"`) ? message : `plan ${sku}: ${message}`;
 
 // src/cli/check/v2.ts
 async function isConfigV2(dir) {
@@ -19096,10 +19107,13 @@ export default function ${pageComponentName(slug)}() {
       <Typography>
         <Heading level={1}>{title}</Heading>
         <p>${text}</p>
-        <Callout type="info" title="Where this page lives">
-          Edit <code>${file}</code>. Files whose name starts with <code>_</code> are not pages, so you can keep shared
-          components next to your pages.
-        </Callout>
+        {/* A note for you while you run the portal locally (\`apitogo dev\`); the deployed portal does not show it. */}
+        {import.meta.env.DEV && (
+          <Callout type="info" title="Where this page lives">
+            Edit <code>${file}</code>. Files whose name starts with <code>_</code> are not pages, so you can keep
+            shared components next to your pages.
+          </Callout>
+        )}
       </Typography>
     </section>
   );
@@ -21330,7 +21344,7 @@ function buildPostPublishChecklist(args) {
   if (args.gatewayUrl) {
     items.push({
       id: "test_gateway",
-      label: "Call the API gateway with Ocp-Apim-Subscription-Key",
+      label: "Call the API gateway with X-API-Key",
       required: false,
       completed: false,
       url: args.gatewayUrl
@@ -26619,7 +26633,9 @@ async function deployGateway(resolved, projectId, deps, options = {}) {
             baseUrl,
             capabilities: capabilities.capabilities,
             openapiUrl: status2.openApiPath ?? void 0,
-            openapiHash: status2.openApiHash ?? status2.specSha256 ?? void 0
+            openapiHash: status2.openApiHash ?? status2.specSha256 ?? void 0,
+            // The portal's keys page and API page show this header (API-120).
+            keyHeaderName: resolved.gateway?.policies.access?.apiKeyHeader ?? DEFAULT_KEY_HEADER
           })
         );
       }

package/dist/declarations/lib/plugins/openapi/util/createHttpSnippet.d.ts

@@ -1,5 +1,7 @@
 import { HTTPSnippet } from "@zudoku/httpsnippet";
 import type { OperationsFragmentFragment } from "../graphql/graphql.js";
+export declare const KEY_HEADER_EXTENSION = "x-apitogo-key-header";
+export declare const KEY_PLACEHOLDER = "YOUR_API_KEY";
 export declare const createHttpSnippet: ({ operation, selectedServer, exampleBody, }: {
     operation: OperationsFragmentFragment;
     selectedServer: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukoweb/apitogo",
-  "version": "0.2.50",
+  "version": "0.2.51",
   "type": "module",
   "sideEffects": [
     "**/*.css",

package/src/config/v2/full-server.ts

@@ -105,7 +105,7 @@ export const FULL_SPEC = (name: string) => `openapi: 3.1.0
 info:
   title: ${JSON.stringify(name)}
   version: 1.0.0
-  description: A small sample API. Edit server/index.js and this file together.
+  description: A sample API with a greeting and a list of items.
 paths:
   /health:
     get:

package/src/config/v2/gateway-reference.ts

@@ -18,7 +18,13 @@ export type ReferenceOptions = {
 };
 
 /** Header of the API key when the gateway does not say otherwise (same as the platform's OpenAPI export). */
-export const DEFAULT_KEY_HEADER = "Ocp-Apim-Subscription-Key";
+export const DEFAULT_KEY_HEADER = "X-API-Key";
+
+/**
+ * Operation extension naming the header a protected operation's key goes in. The API page's code samples read it
+ * (`createHttpSnippet`), so they show the header with a placeholder key.
+ */
+export const KEY_HEADER_EXTENSION = "x-apitogo-key-header";
 
 const METHODS = [
   "get",
@@ -175,10 +181,17 @@ export function buildReferenceSpec(
   else delete doc.components;
   // One requirement with both schemes means both are needed together.
   doc.security = Object.keys(requirement).length > 0 ? [requirement] : [];
-  for (const [, item, method] of operationsOf(paths)) {
+  for (const [path, item, method] of operationsOf(paths)) {
     const operation = item[method] as Json;
     if (Array.isArray(operation.security) && operation.security.length > 0)
       delete operation.security;
+    // The page's code samples add this header, so a copied sample works once the key is filled in (API-120).
+    if (
+      options.apiKeyRequired &&
+      !options.publicOperations.has(actionKey(method, path))
+    )
+      operation[KEY_HEADER_EXTENSION] = options.apiKeyHeader;
+    else delete operation[KEY_HEADER_EXTENSION];
   }
 
   return JSON.parse(hideOrigin(JSON.stringify(doc), options)) as Json;

package/src/config/v2/init.ts

@@ -59,7 +59,7 @@ title: Welcome
 
 # ${name}
 
-This page was created by \`apitogo init\`. Edit it, and add more \`.md\` or \`.mdx\` files next to it: each one becomes a page of your portal.
+Welcome to the ${name} developer portal. Here you will find guides, the API reference, and everything you need to get an API key and make your first call.
 `;
 }
 

package/src/config/v2/starter-landing.ts

@@ -9,15 +9,22 @@ export function starterLandingPage(options: {
 }): string {
   const name = JSON.stringify(options.name);
   const plansImport = options.withPlans
-    ? 'import { usePlansPreview } from "@lukoweb/apitogo-plugin-dev-portal-billing";\n'
+    ? 'import {\n  useGatewayCall,\n  usePlansPreview,\n} from "@lukoweb/apitogo-plugin-dev-portal-billing";\n'
     : "";
   const plansHook = options.withPlans
-    ? "  // The plans of the project's catalog: the same ones the pricing page shows.\n  const plans = usePlansPreview();\n\n"
+    ? "  // The plans of the project's catalog: the same ones the pricing page shows.\n  const plans = usePlansPreview();\n  // The real gateway address and key header, so the sample works when it is pasted with a key.\n  const gateway = useGatewayCall();\n\n"
     : "";
+  // Without the plans service the page cannot learn the gateway, so the sample names the platform's default header.
+  const sampleUrl = options.withPlans
+    ? '${gateway.baseUrl ?? "https://YOUR-GATEWAY"}'
+    : "https://YOUR-GATEWAY";
+  const sampleHeader = options.withPlans ? "${gateway.keyHeader}" : "X-API-Key";
   const plansSection = options.withPlans
     ? "      <PlansPreviewSection plans={plans} />\n"
     : "";
-  return `import {
+  return `// Your portal's home page. Edit this file (apitogo/portal/landing/LandingPage.tsx) to make it yours: everything
+// on it is public, so keep notes for yourself in comments like this one.
+import {
   ApiShowcaseSection,
   FeaturesSection,
   HeroSection,
@@ -47,8 +54,8 @@ ${plansHook}  return (
           {
             filename: "Call the API",
             language: "bash",
-            code: \`$ curl https://your-api.example.com/health \\\\
-  -H "x-api-key: YOUR_API_KEY"
+            code: \`$ curl ${sampleUrl}/health \\\\
+  -H "${sampleHeader}: YOUR_API_KEY"
 # { "status": "ok" }\`,
           },
         ]}
@@ -58,7 +65,7 @@ ${plansHook}  return (
           label: "What you get",
           title: "A developer portal that is ready on day one",
           description:
-            "Edit this page in apitogo/portal/landing/LandingPage.tsx to make it yours.",
+            "Docs, a live API reference, self-service API keys and clear plans, all in one place.",
         }}
         features={[
           {

package/src/config/v2/wrapper.ts

@@ -77,6 +77,10 @@ export type PortalPlan = {
     billing?: string;
     /** Where the account pages link to: only places this portal has (hosted docs, an external docs site, the API page). */
     links?: { docs?: string; api?: string };
+    /** The header API users send their key in, from the gateway entry of services.json (API-120). */
+    keyHeader?: string;
+    /** The gateway's address, for code samples on the portal's pages. */
+    gatewayBaseUrl?: string;
   };
   /** Account pages. */
   userPanel: boolean;
@@ -259,6 +263,10 @@ export function planPortal(
       apiBaseUrl: plans.apiBaseUrl,
       keysApiBaseUrl: plans.keysApiBaseUrl,
       billing: plans.billing,
+      ...(gateway?.keyHeaderName ? { keyHeader: gateway.keyHeaderName } : {}),
+      ...(gateway?.baseUrl && serviceReady(gateway)
+        ? { gatewayBaseUrl: gateway.baseUrl }
+        : {}),
       links: {
         // Hosted docs are linked once their pages are known (see `buildPortalWorkspace`): there is no page to
         // name before that, and a guessed one was a 404 on every portal whose first page is not called `introduction`.

package/src/lib/plugins/openapi/util/createHttpSnippet.ts

@@ -1,135 +1,147 @@
-import { HTTPSnippet } from "@zudoku/httpsnippet";
-import type { OperationsFragmentFragment } from "../graphql/graphql.js";
-
-const toFormDataParams = (text?: string) => {
-  const stringify = (v: unknown) =>
-    typeof v === "string" ? v : JSON.stringify(v);
-
-  try {
-    const obj = text && JSON.parse(text);
-    if (typeof obj !== "object" || !obj) return [];
-
-    return Object.entries(obj).flatMap(([name, value]) => {
-      const values = Array.isArray(value) ? value : [value];
-      return values.map((v) => ({ name, value: stringify(v) }));
-    });
-  } catch {
-    return [];
-  }
-};
-
-export const createHttpSnippet = ({
-  operation,
-  selectedServer,
-  exampleBody,
-}: {
-  operation: OperationsFragmentFragment;
-  selectedServer: string;
-  exampleBody: {
-    mimeType: string;
-    text?: string;
-  };
-}) => {
-  const isMultipart =
-    exampleBody.mimeType === "multipart/form-data" ||
-    exampleBody.mimeType === "application/x-www-form-urlencoded";
-
-  const postData = isMultipart
-    ? {
-        mimeType: exampleBody.mimeType,
-        params: toFormDataParams(exampleBody.text),
-      }
-    : exampleBody;
-
-  return new HTTPSnippet({
-    method: operation.method.toUpperCase(),
-    url:
-      selectedServer + operation.path.replaceAll("{", ":").replaceAll("}", ""),
-    postData,
-    headers: [
-      ...(exampleBody.text
-        ? [{ name: "Content-Type", value: exampleBody.mimeType }]
-        : []),
-      ...(operation.parameters
-        ?.filter((p) => p.in === "header" && p.required === true)
-        .map((p) => ({
-          name: p.name,
-          value:
-            p.schema?.default ??
-            p.examples?.find((x) => x.value)?.value ??
-            (p.schema?.type === "string"
-              ? "<string>"
-              : p.schema?.type === "number" || p.schema?.type === "integer"
-                ? "<number>"
-                : p.schema?.type === "boolean"
-                  ? "<bool>"
-                  : "<value>"),
-        })) ?? []),
-    ],
-    queryString:
-      operation.parameters
-        ?.filter((p) => p.in === "query" && p.required === true)
-        .map((p) => ({
-          name: p.name,
-          value:
-            p.schema?.default ??
-            p.examples?.find((x) => x.value)?.value ??
-            (p.schema?.type === "string"
-              ? "<string>"
-              : p.schema?.type === "number" || p.schema?.type === "integer"
-                ? "<number>"
-                : p.schema?.type === "boolean"
-                  ? "<bool>"
-                  : "<value>"),
-        })) ?? [],
-    httpVersion: "",
-    cookies: [],
-    headersSize: 0,
-    bodySize: 0,
-  });
-};
-
-export const getConverted = (snippet: HTTPSnippet, option: string) => {
-  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
-  let converted: any;
-  switch (option) {
-    case "shell":
-      converted = snippet.convert("shell", "curl");
-      break;
-    case "js":
-      converted = snippet.convert("javascript", "fetch");
-      break;
-    case "python":
-      converted = snippet.convert("python", "requests");
-      break;
-    case "java":
-      converted = snippet.convert("java", "okhttp");
-      break;
-    case "go":
-      converted = snippet.convert("go", "native");
-      break;
-    case "csharp":
-      converted = snippet.convert("csharp", "httpclient");
-      break;
-    case "kotlin":
-      converted = snippet.convert("kotlin", "okhttp");
-      break;
-    case "objc":
-      converted = snippet.convert("objc", "nsurlsession");
-      break;
-    case "php":
-      converted = snippet.convert("php", "http2");
-      break;
-    case "ruby":
-      converted = snippet.convert("ruby");
-      break;
-    case "swift":
-      converted = snippet.convert("swift");
-      break;
-    default:
-      converted = snippet.convert("shell");
-      break;
-  }
-
-  return converted ? converted[0] : "";
-};
+import { HTTPSnippet } from "@zudoku/httpsnippet";
+import type { OperationsFragmentFragment } from "../graphql/graphql.js";
+
+/** Operation extension with the header a key goes in (same name as `KEY_HEADER_EXTENSION` in the CLI's config). */
+export const KEY_HEADER_EXTENSION = "x-apitogo-key-header";
+
+/** What a code sample shows where the visitor's key goes. */
+export const KEY_PLACEHOLDER = "YOUR_API_KEY";
+
+const toFormDataParams = (text?: string) => {
+  const stringify = (v: unknown) =>
+    typeof v === "string" ? v : JSON.stringify(v);
+
+  try {
+    const obj = text && JSON.parse(text);
+    if (typeof obj !== "object" || !obj) return [];
+
+    return Object.entries(obj).flatMap(([name, value]) => {
+      const values = Array.isArray(value) ? value : [value];
+      return values.map((v) => ({ name, value: stringify(v) }));
+    });
+  } catch {
+    return [];
+  }
+};
+
+export const createHttpSnippet = ({
+  operation,
+  selectedServer,
+  exampleBody,
+}: {
+  operation: OperationsFragmentFragment;
+  selectedServer: string;
+  exampleBody: {
+    mimeType: string;
+    text?: string;
+  };
+}) => {
+  const isMultipart =
+    exampleBody.mimeType === "multipart/form-data" ||
+    exampleBody.mimeType === "application/x-www-form-urlencoded";
+
+  const postData = isMultipart
+    ? {
+        mimeType: exampleBody.mimeType,
+        params: toFormDataParams(exampleBody.text),
+      }
+    : exampleBody;
+
+  const keyHeader = operation.extensions?.[KEY_HEADER_EXTENSION];
+
+  return new HTTPSnippet({
+    method: operation.method.toUpperCase(),
+    url:
+      selectedServer + operation.path.replaceAll("{", ":").replaceAll("}", ""),
+    postData,
+    headers: [
+      // The gateway's key header, on operations that need a key (set by the portal build, API-120).
+      ...(typeof keyHeader === "string" && keyHeader
+        ? [{ name: keyHeader, value: KEY_PLACEHOLDER }]
+        : []),
+      ...(exampleBody.text
+        ? [{ name: "Content-Type", value: exampleBody.mimeType }]
+        : []),
+      ...(operation.parameters
+        ?.filter((p) => p.in === "header" && p.required === true)
+        .map((p) => ({
+          name: p.name,
+          value:
+            p.schema?.default ??
+            p.examples?.find((x) => x.value)?.value ??
+            (p.schema?.type === "string"
+              ? "<string>"
+              : p.schema?.type === "number" || p.schema?.type === "integer"
+                ? "<number>"
+                : p.schema?.type === "boolean"
+                  ? "<bool>"
+                  : "<value>"),
+        })) ?? []),
+    ],
+    queryString:
+      operation.parameters
+        ?.filter((p) => p.in === "query" && p.required === true)
+        .map((p) => ({
+          name: p.name,
+          value:
+            p.schema?.default ??
+            p.examples?.find((x) => x.value)?.value ??
+            (p.schema?.type === "string"
+              ? "<string>"
+              : p.schema?.type === "number" || p.schema?.type === "integer"
+                ? "<number>"
+                : p.schema?.type === "boolean"
+                  ? "<bool>"
+                  : "<value>"),
+        })) ?? [],
+    httpVersion: "",
+    cookies: [],
+    headersSize: 0,
+    bodySize: 0,
+  });
+};
+
+export const getConverted = (snippet: HTTPSnippet, option: string) => {
+  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
+  let converted: any;
+  switch (option) {
+    case "shell":
+      converted = snippet.convert("shell", "curl");
+      break;
+    case "js":
+      converted = snippet.convert("javascript", "fetch");
+      break;
+    case "python":
+      converted = snippet.convert("python", "requests");
+      break;
+    case "java":
+      converted = snippet.convert("java", "okhttp");
+      break;
+    case "go":
+      converted = snippet.convert("go", "native");
+      break;
+    case "csharp":
+      converted = snippet.convert("csharp", "httpclient");
+      break;
+    case "kotlin":
+      converted = snippet.convert("kotlin", "okhttp");
+      break;
+    case "objc":
+      converted = snippet.convert("objc", "nsurlsession");
+      break;
+    case "php":
+      converted = snippet.convert("php", "http2");
+      break;
+    case "ruby":
+      converted = snippet.convert("ruby");
+      break;
+    case "swift":
+      converted = snippet.convert("swift");
+      break;
+    default:
+      converted = snippet.convert("shell");
+      break;
+  }
+
+  return converted ? converted[0] : "";
+};