specra 0.1.0

package/src/lib/parsers/openapi-parser.ts

@@ -0,0 +1,251 @@
+import type { SpecraApiSpec, ApiEndpointSpec, ApiParam, ApiResponse } from "../api-parser.types"
+import type { ApiSpecParser } from "./base-parser"
+
+/**
+ * Parser for OpenAPI 3.0/3.1 specifications
+ */
+export class OpenApiParser implements ApiSpecParser {
+  validate(input: any): boolean {
+    return (
+      typeof input === "object" &&
+      input !== null &&
+      ("openapi" in input || "swagger" in input) &&
+      "paths" in input
+    )
+  }
+
+  parse(input: any): SpecraApiSpec {
+    if (!this.validate(input)) {
+      throw new Error("Invalid OpenAPI spec format")
+    }
+
+    const baseUrl = this.extractBaseUrl(input)
+    const endpoints: ApiEndpointSpec[] = []
+
+    // Parse paths
+    for (const [path, pathItem] of Object.entries(input.paths || {})) {
+      const methods = ["get", "post", "put", "patch", "delete"] as const
+
+      for (const method of methods) {
+        const operation = (pathItem as any)[method]
+        if (!operation) continue
+
+        const endpoint = this.parseOperation(path, method.toUpperCase() as any, operation, input)
+        endpoints.push(endpoint)
+      }
+    }
+
+    return {
+      version: input.info?.version,
+      title: input.info?.title,
+      description: input.info?.description,
+      baseUrl,
+      auth: this.extractAuth(input),
+      endpoints,
+    }
+  }
+
+  private extractBaseUrl(spec: any): string {
+    // OpenAPI 3.x servers
+    if (spec.servers && spec.servers.length > 0) {
+      return spec.servers[0].url
+    }
+
+    // Swagger 2.0
+    if (spec.host) {
+      const scheme = spec.schemes?.[0] || "https"
+      const basePath = spec.basePath || ""
+      return `${scheme}://${spec.host}${basePath}`
+    }
+
+    return ""
+  }
+
+  private extractAuth(spec: any): SpecraApiSpec["auth"] {
+    const securitySchemes = spec.components?.securitySchemes || spec.securityDefinitions
+
+    if (!securitySchemes) return undefined
+
+    // Get the first security scheme
+    const firstScheme = Object.values(securitySchemes)[0] as any
+    if (!firstScheme) return undefined
+
+    if (firstScheme.type === "http" && firstScheme.scheme === "bearer") {
+      return {
+        type: "bearer",
+        description: firstScheme.description,
+        tokenPrefix: "Bearer",
+      }
+    }
+
+    if (firstScheme.type === "apiKey") {
+      return {
+        type: "apiKey",
+        description: firstScheme.description,
+        headerName: firstScheme.name || "X-API-Key",
+      }
+    }
+
+    if (firstScheme.type === "http" && firstScheme.scheme === "basic") {
+      return {
+        type: "basic",
+        description: firstScheme.description,
+      }
+    }
+
+    return undefined
+  }
+
+  private parseOperation(
+    path: string,
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
+    operation: any,
+    spec: any
+  ): ApiEndpointSpec {
+    const endpoint: ApiEndpointSpec = {
+      title: operation.summary || operation.operationId || `${method} ${path}`,
+      method,
+      path: this.convertPathParams(path),
+      description: operation.description,
+    }
+
+    // Parse parameters
+    const params = this.parseParameters(operation.parameters || [], spec)
+    if (params.path.length > 0) endpoint.pathParams = params.path
+    if (params.query.length > 0) endpoint.queryParams = params.query
+    if (params.header.length > 0) {
+      endpoint.headers = params.header.map((p) => ({
+        name: p.name,
+        value: p.example || "",
+        description: p.description,
+      }))
+    }
+
+    // Parse request body
+    if (operation.requestBody) {
+      endpoint.body = this.parseRequestBody(operation.requestBody, spec)
+    }
+
+    // Parse responses
+    const responses = this.parseResponses(operation.responses || {}, spec)
+    if (responses.success) endpoint.successResponse = responses.success
+    if (responses.errors.length > 0) endpoint.errorResponses = responses.errors
+
+    return endpoint
+  }
+
+  private convertPathParams(path: string): string {
+    // Convert OpenAPI {param} to :param
+    return path.replace(/\{([^}]+)\}/g, ":$1")
+  }
+
+  private parseParameters(
+    parameters: any[],
+    spec: any
+  ): { path: ApiParam[]; query: ApiParam[]; header: ApiParam[] } {
+    const result = { path: [] as ApiParam[], query: [] as ApiParam[], header: [] as ApiParam[] }
+
+    for (const param of parameters) {
+      // Resolve $ref if present
+      const resolved = param.$ref ? this.resolveRef(param.$ref, spec) : param
+
+      const apiParam: ApiParam = {
+        name: resolved.name,
+        type: resolved.schema?.type || resolved.type || "string",
+        required: resolved.required,
+        description: resolved.description,
+        example: resolved.example || resolved.schema?.example,
+      }
+
+      if (resolved.in === "path") result.path.push(apiParam)
+      else if (resolved.in === "query") result.query.push(apiParam)
+      else if (resolved.in === "header") result.header.push(apiParam)
+    }
+
+    return result
+  }
+
+  private parseRequestBody(requestBody: any, spec: any): ApiEndpointSpec["body"] {
+    const content = requestBody.content?.["application/json"]
+    if (!content) return undefined
+
+    return {
+      description: requestBody.description,
+      example: content.example || this.generateExample(content.schema, spec),
+      schema: content.schema,
+    }
+  }
+
+  private parseResponses(
+    responses: any,
+    spec: any
+  ): { success?: ApiResponse; errors: ApiResponse[] } {
+    const result: { success?: ApiResponse; errors: ApiResponse[] } = { errors: [] }
+
+    for (const [statusCode, response] of Object.entries(responses)) {
+      const status = parseInt(statusCode)
+      if (isNaN(status)) continue
+
+      const resolved = (response as any).$ref ? this.resolveRef((response as any).$ref, spec) : response
+      const content = (resolved as any).content?.["application/json"]
+
+      const apiResponse: ApiResponse = {
+        status,
+        description: (resolved as any).description,
+        example: content?.example || this.generateExample(content?.schema, spec),
+        schema: content?.schema,
+      }
+
+      if (status >= 200 && status < 300) {
+        result.success = apiResponse
+      } else {
+        result.errors.push(apiResponse)
+      }
+    }
+
+    return result
+  }
+
+  private generateExample(schema: any, spec: any): any {
+    if (!schema) return undefined
+    if (schema.$ref) schema = this.resolveRef(schema.$ref, spec)
+    if (schema.example) return schema.example
+
+    // Simple example generation based on schema type
+    if (schema.type === "object" && schema.properties) {
+      const example: any = {}
+      for (const [key, prop] of Object.entries(schema.properties)) {
+        example[key] = this.generateExample(prop, spec)
+      }
+      return example
+    }
+
+    if (schema.type === "array" && schema.items) {
+      return [this.generateExample(schema.items, spec)]
+    }
+
+    // Default values by type
+    const defaults: any = {
+      string: "string",
+      number: 0,
+      integer: 0,
+      boolean: false,
+      object: {},
+      array: [],
+    }
+
+    return defaults[schema.type] || null
+  }
+
+  private resolveRef(ref: string, spec: any): any {
+    const path = ref.replace(/^#\//, "").split("/")
+    let current = spec
+
+    for (const segment of path) {
+      current = current[segment]
+      if (!current) return {}
+    }
+
+    return current
+  }
+}

package/src/lib/parsers/postman-parser.ts

@@ -0,0 +1,301 @@
+import type { SpecraApiSpec, ApiEndpointSpec, ApiParam, ApiHeader } from "../api-parser.types"
+import type { ApiSpecParser } from "./base-parser"
+
+/**
+ * Parser for Postman Collection v2.0/v2.1
+ */
+export class PostmanParser implements ApiSpecParser {
+  validate(input: any): boolean {
+    return (
+      typeof input === "object" &&
+      input !== null &&
+      "info" in input &&
+      input.info?.schema?.includes("v2")
+    )
+  }
+
+  parse(input: any): SpecraApiSpec {
+    if (!this.validate(input)) {
+      throw new Error("Invalid Postman Collection format (requires v2.0 or v2.1)")
+    }
+
+    const baseUrl = this.extractBaseUrl(input)
+    const endpoints: ApiEndpointSpec[] = []
+
+    // Parse items (can be nested in folders)
+    this.parseItems(input.item || [], endpoints, baseUrl, input)
+
+    return {
+      version: input.info?.version,
+      title: input.info?.name,
+      description: input.info?.description,
+      baseUrl,
+      auth: this.extractAuth(input.auth),
+      globalHeaders: this.extractGlobalHeaders(input),
+      endpoints,
+    }
+  }
+
+  private extractBaseUrl(collection: any): string {
+    // Try to get from variables
+    const baseUrlVar = collection.variable?.find(
+      (v: any) => v.key === "baseUrl" || v.key === "base_url" || v.key === "url"
+    )
+    if (baseUrlVar) return baseUrlVar.value
+
+    // Try to extract from first request
+    if (collection.item && collection.item.length > 0) {
+      const firstRequest = this.findFirstRequest(collection.item)
+      if (firstRequest?.request?.url) {
+        const url = this.parseUrl(firstRequest.request.url)
+        if (url.host) {
+          return `${url.protocol}://${url.host.join(".")}`
+        }
+      }
+    }
+
+    return ""
+  }
+
+  private findFirstRequest(items: any[]): any {
+    for (const item of items) {
+      if (item.request) return item
+      if (item.item) {
+        const found = this.findFirstRequest(item.item)
+        if (found) return found
+      }
+    }
+    return null
+  }
+
+  private extractAuth(auth: any): SpecraApiSpec["auth"] {
+    if (!auth) return undefined
+
+    if (auth.type === "bearer") {
+      return {
+        type: "bearer",
+        tokenPrefix: "Bearer",
+      }
+    }
+
+    if (auth.type === "apikey") {
+      const keyData = auth.apikey?.find((a: any) => a.key === "key")
+      const keyName = keyData?.value || "X-API-Key"
+
+      return {
+        type: "apiKey",
+        headerName: keyName,
+      }
+    }
+
+    if (auth.type === "basic") {
+      return {
+        type: "basic",
+      }
+    }
+
+    return undefined
+  }
+
+  private extractGlobalHeaders(collection: any): ApiHeader[] {
+    // Postman doesn't have global headers in the same way, but we can check for common patterns
+    return []
+  }
+
+  private parseItems(items: any[], endpoints: ApiEndpointSpec[], baseUrl: string, collection: any) {
+    for (const item of items) {
+      // If it's a folder, recurse
+      if (item.item && Array.isArray(item.item)) {
+        this.parseItems(item.item, endpoints, baseUrl, collection)
+      }
+      // If it's a request
+      else if (item.request) {
+        const endpoint = this.parseRequest(item, baseUrl, collection)
+        endpoints.push(endpoint)
+      }
+    }
+  }
+
+  private parseRequest(item: any, baseUrl: string, collection: any): ApiEndpointSpec {
+    const request = item.request
+    const url = this.parseUrl(request.url)
+
+    const endpoint: ApiEndpointSpec = {
+      title: item.name,
+      method: request.method.toUpperCase(),
+      path: this.buildPath(url, baseUrl),
+      description: item.request.description || item.description,
+    }
+
+    // Parse URL parameters (path and query)
+    const params = this.parseUrlParams(url)
+    if (params.path.length > 0) endpoint.pathParams = params.path
+    if (params.query.length > 0) endpoint.queryParams = params.query
+
+    // Parse headers
+    if (request.header && request.header.length > 0) {
+      endpoint.headers = request.header
+        .filter((h: any) => !h.disabled)
+        .map((h: any) => ({
+          name: h.key,
+          value: h.value || "",
+          description: h.description,
+        }))
+    }
+
+    // Parse request body
+    if (request.body) {
+      endpoint.body = this.parseBody(request.body)
+    }
+
+    // Parse response examples
+    const responses = this.parseResponses(item.response || [])
+    if (responses.success) endpoint.successResponse = responses.success
+    if (responses.errors.length > 0) endpoint.errorResponses = responses.errors
+
+    return endpoint
+  }
+
+  private parseUrl(url: any): {
+    protocol: string
+    host: string[]
+    path: string[]
+    query: any[]
+    variable: any[]
+  } {
+    if (typeof url === "string") {
+      // Parse string URL
+      const urlObj = new URL(url)
+      return {
+        protocol: urlObj.protocol.replace(":", ""),
+        host: urlObj.hostname.split("."),
+        path: urlObj.pathname.split("/").filter(Boolean),
+        query: [],
+        variable: [],
+      }
+    }
+
+    return {
+      protocol: url.protocol || "https",
+      host: url.host || [],
+      path: url.path || [],
+      query: url.query || [],
+      variable: url.variable || [],
+    }
+  }
+
+  private buildPath(url: any, baseUrl: string): string {
+    let path = "/"
+
+    if (url.path && url.path.length > 0) {
+      path += url.path.join("/")
+    }
+
+    // Convert Postman :param to our :param format (they're the same!)
+    // But we need to handle {{variable}} syntax
+    path = path.replace(/\{\{([^}]+)\}\}/g, ":$1")
+
+    return path
+  }
+
+  private parseUrlParams(url: any): { path: ApiParam[]; query: ApiParam[] } {
+    const result = { path: [] as ApiParam[], query: [] as ApiParam[] }
+
+    // Path parameters from variables
+    if (url.variable && url.variable.length > 0) {
+      for (const v of url.variable) {
+        result.path.push({
+          name: v.key,
+          type: v.type || "string",
+          description: v.description,
+          example: v.value,
+        })
+      }
+    }
+
+    // Extract path params from the path itself
+    if (url.path && url.path.length > 0) {
+      for (const segment of url.path) {
+        if (segment.startsWith(":")) {
+          const paramName = segment.slice(1)
+          // Only add if not already added from variables
+          if (!result.path.find((p) => p.name === paramName)) {
+            result.path.push({
+              name: paramName,
+              type: "string",
+            })
+          }
+        }
+      }
+    }
+
+    // Query parameters
+    if (url.query && url.query.length > 0) {
+      for (const q of url.query) {
+        if (q.disabled) continue
+        result.query.push({
+          name: q.key,
+          type: "string",
+          description: q.description,
+          example: q.value,
+        })
+      }
+    }
+
+    return result
+  }
+
+  private parseBody(body: any): ApiEndpointSpec["body"] {
+    if (!body) return undefined
+
+    let example: any
+    let description = body.description
+
+    if (body.mode === "raw") {
+      try {
+        example = JSON.parse(body.raw)
+      } catch {
+        example = body.raw
+      }
+    } else if (body.mode === "formdata" || body.mode === "urlencoded") {
+      example = {}
+      for (const item of body[body.mode] || []) {
+        if (!item.disabled) {
+          example[item.key] = item.value
+        }
+      }
+    }
+
+    return {
+      description,
+      example,
+    }
+  }
+
+  private parseResponses(responses: any[]): { success?: any; errors: any[] } {
+    const result: { success?: any; errors: any[] } = { errors: [] }
+
+    for (const response of responses) {
+      let example: any
+      try {
+        example = JSON.parse(response.body)
+      } catch {
+        example = response.body
+      }
+
+      const apiResponse = {
+        status: response.code || 200,
+        description: response.name,
+        example,
+      }
+
+      if (apiResponse.status >= 200 && apiResponse.status < 300) {
+        if (!result.success) result.success = apiResponse
+      } else {
+        result.errors.push(apiResponse)
+      }
+    }
+
+    return result
+  }
+}

package/src/lib/parsers/specra-parser.ts

@@ -0,0 +1,24 @@
+import type { SpecraApiSpec } from "../api-parser.types"
+import type { ApiSpecParser } from "./base-parser"
+
+/**
+ * Parser for native Specra API format
+ * This is a pass-through parser since the input is already in the correct format
+ */
+export class SpecraParser implements ApiSpecParser {
+  validate(input: any): boolean {
+    return (
+      typeof input === "object" &&
+      input !== null &&
+      "endpoints" in input &&
+      Array.isArray(input.endpoints)
+    )
+  }
+
+  parse(input: any): SpecraApiSpec {
+    if (!this.validate(input)) {
+      throw new Error("Invalid Specra API spec format")
+    }
+    return input as SpecraApiSpec
+  }
+}

package/src/lib/redirects.ts

@@ -0,0 +1,40 @@
+import { getAllDocs, getVersions } from "./mdx"
+
+export interface RedirectMapping {
+  from: string
+  to: string
+}
+
+/**
+ * Build redirect mappings from all docs' redirect_from frontmatter
+ */
+export async function buildRedirectMappings(): Promise<RedirectMapping[]> {
+  const versions = getVersions()
+  const redirects: RedirectMapping[] = []
+
+  for (const version of versions) {
+    const docs = await getAllDocs(version)
+    
+    for (const doc of docs) {
+      if (doc.meta.redirect_from && Array.isArray(doc.meta.redirect_from)) {
+        for (const oldPath of doc.meta.redirect_from) {
+          redirects.push({
+            from: oldPath,
+            to: `/docs/${version}/${doc.slug}`,
+          })
+        }
+      }
+    }
+  }
+
+  return redirects
+}
+
+/**
+ * Find redirect destination for a given path
+ */
+export async function findRedirect(path: string): Promise<string | null> {
+  const redirects = await buildRedirectMappings()
+  const redirect = redirects.find((r) => r.from === path)
+  return redirect ? redirect.to : null
+}

package/src/lib/remark-code-meta.ts

@@ -0,0 +1,23 @@
+/**
+ * Remark plugin to extract code block meta strings and pass them as props
+ * Converts: ```js filename.js
+ * Into props: { language: 'js', meta: 'filename.js' }
+ */
+export function remarkCodeMeta() {
+  return (tree: any) => {
+    const visit = (node: any) => {
+      if (node.type === 'code' && node.meta) {
+        // Store the meta string in the node's data
+        node.data = node.data || {}
+        node.data.hProperties = node.data.hProperties || {}
+        node.data.hProperties.meta = node.meta
+      }
+      
+      if (node.children) {
+        node.children.forEach(visit)
+      }
+    }
+    
+    visit(tree)
+  }
+}