@thallylabs/migrate 0.2.17 → 0.2.19

package/README.md

@@ -11,7 +11,13 @@ authored nesting or order. The adapter supports tabs, dropdowns, products,
 versions, languages, and reusable `$ref` navigation files; it also preserves
 dropdown presentation, collection descriptions and icons, explicit default
 versions, page route casing, redirects, local snippets, static assets,
-compatible page frontmatter, site identity, and OpenAPI configuration. For public Mintlify
+compatible page frontmatter, site identity, and OpenAPI configuration.
+Analytics come across too: docs.json `integrations` and legacy mint.json
+`analytics` for GA4, Google Tag Manager, PostHog, and Plausible are validated
+and written to `docs.json` `integrations` (`integrations` wins per provider when
+both exist). Invalid values are skipped with a warning, and every other
+Mintlify provider (Amplitude, Mixpanel, Segment, and so on) is listed once in a
+warning instead of being dropped silently. For public Mintlify
 sites, the URL adapter reads the structured configuration embedded in the
 rendered application before falling back to DOM link inference.
 
@@ -34,6 +40,13 @@ instead of silently dropping that API tab's reference. AsyncAPI has no Thally
 renderer, so it always produces a clear warning naming the spec instead of
 disappearing.
 
+Page `openapi:` frontmatter with a spec prefix
+(`openapi: "specs/openapi-b.yaml GET /widgets/{id}"`) is rewritten to where the
+spec lands in the output (`/openapi-b.yaml GET /widgets/{id}`). A prefix naming
+a spec that was not migrated is kept and reported. Manual API pages keep their
+`api:` and `authMethod:` frontmatter, and `api.mdx.server` / `api.mdx.auth` map
+into `docs.json`; invalid values are dropped with a warning.
+
 In-content links to auto-generated API operation pages are rewritten to the
 matching Thally `/api/...` route. A link under a known API section that matches
 no operation points to that section's overview page instead, and one warning

package/dist/index.d.ts

@@ -128,6 +128,34 @@ interface MigrationDocsConfig {
     analytics?: {
         enabled?: boolean;
     };
+    /** Manual API pages: default server(s) and auth for `api:` frontmatter pages. */
+    api?: {
+        mdx?: {
+            server?: string | Array<string>;
+            auth?: {
+                method?: 'bearer' | 'basic' | 'key';
+                name?: string;
+            };
+        };
+    };
+    /** Third-party analytics in Mintlify's `integrations` shape; validated again by the renderer. */
+    integrations?: {
+        ga4?: {
+            measurementId: string;
+        };
+        gtm?: {
+            tagId: string;
+        };
+        posthog?: {
+            apiKey: string;
+            apiHost?: string;
+            sessionRecording?: boolean;
+        };
+        plausible?: {
+            domain: string;
+            server?: string;
+        };
+    };
     redirects?: Array<{
         source: string;
         destination: string;
@@ -161,6 +189,10 @@ interface MigrationPage {
     noindex?: boolean;
     /** OpenAPI operation key rendered by Thally instead of ordinary MDX. */
     openapi?: string;
+    /** Manual API page: `METHOD <url-or-path>`; rendered by Thally's playground. */
+    api?: string;
+    /** Page-level playground auth override: bearer | basic | key | none. */
+    authMethod?: string;
     body: string;
     source: string;
     /** Set when the page's frontmatter was invalid YAML; the page is kept with a best-effort salvage. */
@@ -445,8 +477,30 @@ declare function parseMarkdownPage(input: {
     platform?: MigrationPlatform;
     /** Resolve platform-specific routes from the already-parsed frontmatter. */
     resolveIdentity?: (frontmatter: Record<string, unknown>, fallback: MarkdownPageIdentity) => MarkdownPageIdentity;
+    /** Receives a message when frontmatter is dropped or altered. */
+    warn?: (message: string) => void;
 }): MigrationPage | null;
 
+/**
+ * Mintlify analytics -> Thally `docs.json` `integrations`.
+ *
+ * Reads docs.json `integrations` and the legacy mint.json `analytics` block.
+ * Values land in an inline script on the rendered site, so each is validated
+ * here with the same patterns the renderer applies (src/lib/analytics-config.ts;
+ * a test keeps the two in agreement). Invalid values are skipped with a warning,
+ * never coerced, and no warning echoes a full value.
+ */
+type MigrationIntegrations = NonNullable<MigrationDocsConfig['integrations']>;
+declare function projectMintlifyIntegrations(config: Record<string, unknown>): {
+    integrations?: MigrationIntegrations;
+    warnings: Array<MigrationWarning>;
+};
+/**
+ * Validate an authored Thally `docs.json` `integrations` value with the same
+ * rules as the import and the renderer; one value-free message per problem.
+ */
+declare function validateIntegrations(integrations: unknown): Array<string>;
+
 /** Render canonical migration bundles into a portable Thally repository tree. */
 
 /** Merge imported tabs into an existing site without duplicating changelog tabs. */
@@ -486,4 +540,4 @@ declare function migrateUrl(options: UrlMigrationOptions): Promise<MigrationBund
  */
 declare function hydrateRemoteApiSpecs(bundle: MigrationBundle, fetcher?: MigrationFetcher): Promise<MigrationBundle>;
 
-export { type GitHubRepositorySource, type MigrationAsset, type MigrationBundle, type MigrationDocsConfig, type MigrationFetchRequest, type MigrationFetchResponse, type MigrationFetcher, type MigrationNavigationGroup, type MigrationNavigationTab, type MigrationPage, type MigrationPlatform, type MigrationWarning, type RenderedMigrationFile, type RepositoryMigrationOptions, type UrlMigrationOptions, addMintlifyDirectoryRedirects, buildNavigationFromPages, cloneGitHubRepository, defaultMigrationFetcher, detectRepositoryDocsDir, detectRepositoryPlatform, gitmodulePaths, hydrateRemoteApiSpecs, mergeMigrationConfig, migrateRepository, migrateUrl, normalizeMdx, parseGitHubRepositoryUrl, parseMarkdownPage, projectFernNavigation, projectMintlifyNavigation, pruneMissingNavigationPages, readFernConfig, readMintlifyConfig, renderMigrationFiles, validateMigrationUrl };
+export { type GitHubRepositorySource, type MigrationAsset, type MigrationBundle, type MigrationDocsConfig, type MigrationFetchRequest, type MigrationFetchResponse, type MigrationFetcher, type MigrationNavigationGroup, type MigrationNavigationTab, type MigrationPage, type MigrationPlatform, type MigrationWarning, type RenderedMigrationFile, type RepositoryMigrationOptions, type UrlMigrationOptions, addMintlifyDirectoryRedirects, buildNavigationFromPages, cloneGitHubRepository, defaultMigrationFetcher, detectRepositoryDocsDir, detectRepositoryPlatform, gitmodulePaths, hydrateRemoteApiSpecs, mergeMigrationConfig, migrateRepository, migrateUrl, normalizeMdx, parseGitHubRepositoryUrl, parseMarkdownPage, projectFernNavigation, projectMintlifyIntegrations, projectMintlifyNavigation, pruneMissingNavigationPages, readFernConfig, readMintlifyConfig, renderMigrationFiles, validateIntegrations, validateMigrationUrl };