@scalar/import 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @scalar/import
+
+## 0.0.1
+
+### Patch Changes
+
+- e930134: feat: new @scalar/import package :)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present Scalar
+
+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

@@ -0,0 +1,61 @@
+# Scalar Import
+
+[![Version](https://img.shields.io/npm/v/%40scalar/import)](https://www.npmjs.com/package/@scalar/import)
+[![Downloads](https://img.shields.io/npm/dm/%40scalar/import)](https://www.npmjs.com/package/@scalar/import)
+[![License](https://img.shields.io/npm/l/%40scalar%2Fimport)](https://www.npmjs.com/package/@scalar/import)
+[![Discord](https://img.shields.io/discord/1135330207960678410?style=flat&color=5865F2)](https://discord.gg/scalar)
+
+Pass an URL to an OpenAPI document, a Swagger document, a Postman collection, a Scalar API reference, a Scalar Sandbox link … basically anything, and retrieve an OpenAPI document.
+
+## Installation
+
+```bash
+npm install @scalar/import
+```
+
+## Usage
+
+Find any OpenAPI/Swagger document URL in any content:
+
+```ts
+import { resolve } from '@scalar/import'
+
+// Get the Swagger 2.0 URL from Swagger UI
+const result = await resolve('https://petstore.swagger.io/')
+
+// https://petstore.swagger.io/v2/swagger.json
+```
+
+## Features
+
+- Resolves URLs to OpenAPI specifications from various sources
+- Supports JSON and YAML formats (`.json`, `.yaml`, `.yml`)
+- Extracts OpenAPI specification URLs from HTML content, including:
+  - Scalar API Reference `<script>` tags
+  - Redoc HTML and JavaScript implementations
+- Works with different quote styles and data attribute formats
+- Robust error handling for various HTML structures
+- Transforms GitHub URLs to raw file URLs
+- Handles Scalar Sandbox URLs
+
+### Examples
+
+| Input                                                                  | Output                                                                    | Description                                                          |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json           | Same as input                                                             | Returns JSON URLs as-is                                              |
+| https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml or \*.yml | Same as input                                                             | Returns YAML URLs as-is                                              |
+| https://sandbox.scalar.com/p/dlw8v                                     | https://sandbox.scalar.com/files/dlw8v/openapi.yaml                       | Resolves sandbox URLs to specific file paths                         |
+| https://github.com/owner/repo/blob/main/openapi.yaml                   | https://raw.githubusercontent.com/owner/repo/refs/heads/main/openapi.yaml | Transforms GitHub URLs to raw file URLs                              |
+| HTML with data-url attribute                                           | URL from data-url attribute                                               | Extracts URL from HTML script tag with data-url attribute            |
+| HTML with relative URL `/openapi.yaml`                                 | https://example.com/openapi.yaml                                          | Resolves relative URLs to absolute URLs                              |
+| HTML with JSON configuration                                           | URL from JSON configuration                                               | Extracts URL from JSON configuration in data-configuration attribute |
+| Redoc HTML                                                             | URL from spec-url attribute                                               | Extracts URL from Redoc's spec-url attribute                         |
+| HTML with embedded OpenAPI                                             | Parsed OpenAPI object                                                     | Extracts and parses embedded OpenAPI JSON from HTML                  |
+
+## Community
+
+We are API nerds. You too? Let’s chat on Discord: <https://discord.gg/scalar>
+
+## License
+
+The source code in this repository is licensed under [MIT](https://github.com/scalar/openapi-parser/blob/main/LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './resolve.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { resolve } from './resolve.js';

package/dist/resolve.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Find an OpenAPI document URL in the HTML of @scalar/api-reference and other places.
+ * This is useful to open the OpenAPI document from basically any source.
+ */
+export declare function resolve(value?: string): Promise<string | Record<string, any> | undefined>;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC,CA0DnD"}

package/dist/resolve.js

@@ -0,0 +1,146 @@
+/**
+ * Find an OpenAPI document URL in the HTML of @scalar/api-reference and other places.
+ * This is useful to open the OpenAPI document from basically any source.
+ */
+async function resolve(value) {
+    // URLs
+    if (value?.startsWith('http://') || value?.startsWith('https://')) {
+        // Transform GitHub URLs to raw file URLs
+        const githubRawUrl = transformGitHubUrl(value);
+        if (githubRawUrl) {
+            return githubRawUrl;
+        }
+        // https://*.json
+        if (value?.toLowerCase().endsWith('.json')) {
+            return value;
+        }
+        // https://*.yaml
+        if (value?.toLowerCase().endsWith('.yaml') ||
+            value?.toLowerCase().endsWith('.yml')) {
+            return value;
+        }
+        // https://sandbox.scalar.com
+        const sandboxUrl = value.match(/https:\/\/sandbox\.scalar\.com\/(p|e)\/([a-z0-9]+)/);
+        if (sandboxUrl?.[2]) {
+            return `https://sandbox.scalar.com/files/${sandboxUrl[2]}/openapi.yaml`;
+        }
+        // Fetch URL
+        try {
+            const result = await fetch(value);
+            if (result.ok) {
+                const content = await result.text();
+                const urlOrPath = parseHtml(content);
+                if (urlOrPath) {
+                    return makeRelativeUrlsAbsolute(value, urlOrPath);
+                }
+                // New: Check for embedded OpenAPI document
+                const embeddedSpec = parseEmbeddedOpenApi(content);
+                if (embeddedSpec) {
+                    return embeddedSpec;
+                }
+            }
+            else {
+                console.warn(`[@scalar/import] Failed to fetch ${value}`);
+            }
+        }
+        catch (error) {
+            console.error(`[@scalar/import] Failed to fetch ${value}`, error);
+        }
+    }
+    return undefined;
+}
+/**
+ * Go through the HTML and try to find the OpenAPI document URL
+ */
+function parseHtml(html) {
+    // Check whether it could be HTML
+    if (!html?.includes('<')) {
+        return undefined;
+    }
+    // data-url="*"
+    const dataUrlMatch = html.match(/data-url=["']([^"']+)["']/);
+    if (dataUrlMatch?.[1]) {
+        return dataUrlMatch[1];
+    }
+    // spec-url="*"
+    const specUrlMatch = html.match(/spec-url=["']([^"']+)["']/);
+    if (specUrlMatch?.[1]) {
+        return specUrlMatch[1];
+    }
+    // Redoc.init('*')
+    const redocInit = html.match(/Redoc.init\(["']([^"']+)["']/);
+    if (redocInit?.[1]) {
+        return redocInit[1];
+    }
+    // &amp;quot;url&amp;quot;:&amp;quot;MY_CUSTOM_URL&amp;quot;
+    const configurationUrl = html.match(/&amp;quot;url&amp;quot;:&amp;quot;([^;]+)&amp;quot;/);
+    if (configurationUrl?.[1]) {
+        return configurationUrl[1];
+    }
+    return undefined;
+}
+/**
+ * URLs can be relative, but we need absolute URLs eventually.
+ */
+function makeRelativeUrlsAbsolute(baseUrl, path) {
+    // Check whether the path is already absolute
+    if (path.startsWith('http://') || path.startsWith('https://')) {
+        return path;
+    }
+    // Combine the URL and the relative path
+    try {
+        const { href } = new URL(path, baseUrl);
+        return href;
+    }
+    catch (error) {
+        // Return original path if URL creation fails
+        console.error('[makeRelativeUrlsAbsolute] Error combining URLs:', error);
+        return path;
+    }
+}
+/**
+ * Parse embedded OpenAPI document from HTML
+ */
+function parseEmbeddedOpenApi(html) {
+    const match = html.match(/<script[^>]*data-configuration=['"]([^'"]+)['"][^>]*>(.*?)<\/script>/);
+    if (!match)
+        return undefined;
+    try {
+        const configString = decodeHtmlEntities(match[1]);
+        const config = JSON.parse(configString);
+        if (config.spec?.content) {
+            return config.spec.content;
+        }
+    }
+    catch (error) {
+        console.error('[@scalar/import] Failed to parse embedded OpenAPI document:', error);
+    }
+    return undefined;
+}
+/**
+ * Decode HTML entities in a string
+ */
+function decodeHtmlEntities(text) {
+    const entities = {
+        '&amp;': '&',
+        '&lt;': '<',
+        '&gt;': '>',
+        '&quot;': '"',
+        '&#39;': "'",
+    };
+    return text.replace(new RegExp(Object.keys(entities).join('|'), 'g'), (match) => entities[match]);
+}
+/**
+ * Transform GitHub URLs to raw file URLs, preserving the branch information
+ */
+function transformGitHubUrl(url) {
+    const githubRegex = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/([^/]+)\/(.+)$/;
+    const match = url.match(githubRegex);
+    if (match) {
+        const [, owner, repo, branch, path] = match;
+        return `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${branch}/${path}`;
+    }
+    return undefined;
+}
+
+export { resolve };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@scalar/import",
+  "description": "Import any file, URL or content to get an OpenAPI document",
+  "license": "MIT",
+  "author": "Scalar (https://github.com/scalar)",
+  "homepage": "https://github.com/scalar/scalar",
+  "bugs": "https://github.com/scalar/scalar/issues/new/choose",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scalar/scalar.git",
+    "directory": "packages/import"
+  },
+  "keywords": [
+    "openapi",
+    "swagger",
+    "postman",
+    "scalar"
+  ],
+  "version": "0.0.1",
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "module": "dist/index.js",
+  "dependencies": {
+    "@scalar/openapi-parser": "0.8.7"
+  },
+  "devDependencies": {
+    "vite": "^5.2.10",
+    "@scalar/build-tooling": "0.1.11"
+  },
+  "scripts": {
+    "build": "scalar-build-rollup",
+    "dev": "nodemon --exec \"vite-node playground/index.ts\" --ext ts --quiet",
+    "lint:check": "eslint .",
+    "lint:fix": "eslint .  --fix",
+    "test": "vitest",
+    "types:build": "scalar-types-build",
+    "types:check": "scalar-types-check"
+  }
+}