continued imprvoements

Author: alexphelps

app/globals.css

@@ -99,3 +99,8 @@ div[style*="--callout-color"] > svg {
 div[style*="--callout-color"] > div[role="none"] {
   display: none !important;
 }
+
+/* Callout description uses text-fd-muted-foreground — override it to full foreground */
+div[style*="--callout-color"] {
+  --color-fd-muted-foreground: var(--color-fd-foreground);
+}

content/docs/admin-api/index.mdx

@@ -7,14 +7,11 @@ import { Callout } from 'fumadocs-ui/components/callout';
 
 ### Getting Started
 
-{/* At the core of Next Commerce is the Admin API, developers can seamless build custom store operations, create orders, and integrate third-party services. Empower your business with streamlined control and endless possibilities, all through our intuitive and powerful API. */}
-
 At the core of Next Commerce is the Admin API, developers can manage store resources, integrate third-party services and build seamless external order flows.
 
 
 ### Authentication
 
-
 The Admin API uses Oauth 2 authorization protocol to manage access to your store's resources. Oauth Apps (and associated access tokens) can be tailored with object-level permission to ensure that each integrated service only has access to necessary objects.
 
 Before using the Admin API, you'll need to create a store and create an OAuth App necessary for API access. To create an OAuth App, navigate to **Settings > API Access** and create a new Oauth App with applicable [permissions](/docs/admin-api/permissions) to retrieve your **Access Token**.  It is recommended to create unique Oauth Apps per external system so that you can revoke as needed.

content/docs/admin-api/reference/2023-02-10/meta.json

@@ -3,18 +3,18 @@
   "title": "API Reference",
   "pages": [
     "apps",
-    "carts",
-    "customers",
     "fulfillment",
+    "carts",
+    "products",
+    "payments",
     "gift-cards",
     "metadata",
     "orders",
-    "payments",
-    "products",
-    "store",
     "storefront",
+    "store",
     "subscriptions",
     "support",
+    "customers",
     "webhooks"
   ]
 }

content/docs/admin-api/reference/meta.json

@@ -2,18 +2,18 @@
   "title": "API Reference",
   "pages": [
     "apps",
-    "carts",
-    "customers",
     "fulfillment",
+    "carts",
+    "products",
+    "payments",
     "gift-cards",
     "metadata",
     "orders",
-    "payments",
-    "products",
-    "store",
     "storefront",
+    "store",
     "subscriptions",
     "support",
+    "customers",
     "webhooks"
   ]
 }

content/docs/admin-api/reference/unstable/meta.json

@@ -3,18 +3,18 @@
   "title": "API Reference",
   "pages": [
     "apps",
-    "carts",
-    "customers",
     "fulfillment",
+    "carts",
+    "products",
+    "payments",
     "gift-cards",
     "metadata",
     "orders",
-    "payments",
-    "products",
-    "store",
     "storefront",
+    "store",
     "subscriptions",
     "support",
+    "customers",
     "webhooks"
   ]
 }

scripts/generate-api-docs.mjs

@@ -143,6 +143,36 @@ function isWebhookFile(filename) {
   return filename.includes('.');
 }
 
+/**
+ * Extract the tag order from an OpenAPI spec by first-appearance in paths.
+ * Returns an array of tag names in spec order.
+ */
+function getTagOrder(specPath) {
+  const raw = readFileSync(specPath, 'utf8');
+  const spec = yaml.load(raw);
+  if (spec.tags?.length) return spec.tags.map(t => t.name);
+  const seen = [];
+  for (const methods of Object.values(spec.paths ?? {})) {
+    for (const op of Object.values(methods)) {
+      if (!op || typeof op !== 'object') continue;
+      for (const tag of op.tags ?? []) {
+        if (!seen.includes(tag)) seen.push(tag);
+      }
+    }
+  }
+  return seen;
+}
+
+/**
+ * Sort tag folders to match spec order; any folders not in spec go at the end alphabetically.
+ */
+function sortBySpecOrder(folders, specOrder) {
+  return [
+    ...specOrder.filter(t => folders.includes(t)),
+    ...folders.filter(t => !specOrder.includes(t)).sort(),
+  ];
+}
+
 /**
  * Scan generated MDX files and return a map of URL path → HTTP method.
  * urlBase is the /docs/... prefix for this output directory.
@@ -293,10 +323,13 @@ for (const wspec of WEBHOOK_SPECS) {
 
 // For the default admin-api reference dir, write a meta.json listing tag folders
 const refDir = 'content/docs/admin-api/reference';
-const tagFolders = readdirSync(refDir, { withFileTypes: true })
-  .filter(e => e.isDirectory() && !VERSION_SUBFOLDERS.includes(e.name))
-  .map(e => e.name)
-  .sort();
+const stableTagOrder = getTagOrder(specs[0].input[0]);
+const tagFolders = sortBySpecOrder(
+  readdirSync(refDir, { withFileTypes: true })
+    .filter(e => e.isDirectory() && !VERSION_SUBFOLDERS.includes(e.name))
+    .map(e => e.name),
+  stableTagOrder,
+);
 // root:true version subdirs are discovered automatically — don't add to pages array
 writeFileSync(
   join(refDir, 'meta.json'),
@@ -308,10 +341,14 @@ console.log(`Wrote reference/meta.json with tag folders: ${tagFolders.join(', ')
 for (const version of VERSION_SUBFOLDERS) {
   const versionDir = join(refDir, version);
   if (!existsSync(versionDir)) continue;
-  const versionTagFolders = readdirSync(versionDir, { withFileTypes: true })
-    .filter(e => e.isDirectory())
-    .map(e => e.name)
-    .sort();
+  const versionSpecPath = specs.find(s => s.output === versionDir)?.input[0] ?? specs[0].input[0];
+  const versionTagOrder = getTagOrder(versionSpecPath);
+  const versionTagFolders = sortBySpecOrder(
+    readdirSync(versionDir, { withFileTypes: true })
+      .filter(e => e.isDirectory())
+      .map(e => e.name),
+    versionTagOrder,
+  );
   writeFileSync(
     join(versionDir, 'meta.json'),
     JSON.stringify({ root: true, title: 'API Reference', pages: versionTagFolders }, null, 2),
@@ -321,10 +358,13 @@ for (const version of VERSION_SUBFOLDERS) {
 
 // For the campaigns api dir, write a meta.json listing tag folders (same pattern as admin-api)
 const campaignsApiDir = 'content/docs/campaigns/api';
-const campaignsTagFolders = readdirSync(campaignsApiDir, { withFileTypes: true })
-  .filter(e => e.isDirectory() && !CAMPAIGNS_VERSION_SUBFOLDERS.includes(e.name))
-  .map(e => e.name)
-  .sort();
+const campaignsTagOrder = getTagOrder(specs.find(s => s.output === campaignsApiDir).input[0]);
+const campaignsTagFolders = sortBySpecOrder(
+  readdirSync(campaignsApiDir, { withFileTypes: true })
+    .filter(e => e.isDirectory() && !CAMPAIGNS_VERSION_SUBFOLDERS.includes(e.name))
+    .map(e => e.name),
+  campaignsTagOrder,
+);
 // root:true version subdirs are discovered automatically — don't add to pages array
 writeFileSync(
   join(campaignsApiDir, 'meta.json'),