@docslurp/contrib-astro 0.3.0 → 0.4.0

package/DocSlurpSearch.astro

@@ -1,13 +1,16 @@
 ---
+import { assertBrowserSafeApiKey, assertSecureApiOrigin } from "@docslurp/sdk";
 /**
  * Browser key only: restrict it to this site's origin and the search scope.
- * workspaceId takes a slug, UUID or "default" (the key organization's default
+ * workspace takes an ID, slug or name, or "default" (the key organization's default
  * workspace) and defaults to "default"; apiUrl defaults to https://docslurp.io.
  */
-interface Props { clientKey: string; workspaceId?: string; apiUrl?: string; placeholder?: string; }
-const { clientKey, workspaceId = 'default', apiUrl = 'https://docslurp.io', placeholder = 'Search documents…' } = Astro.props;
+interface Props { clientKey: string; workspace?: string; apiUrl?: string; placeholder?: string; }
+const { clientKey, workspace = 'default', apiUrl = 'https://docslurp.io', placeholder = 'Search documents…' } = Astro.props;
+assertBrowserSafeApiKey(clientKey, true);
+assertSecureApiOrigin(apiUrl);
 ---
-<docslurp-search-box api-url={apiUrl} workspace-id={workspaceId} client-key={clientKey} placeholder={placeholder}></docslurp-search-box>
+<docslurp-search-box api-url={apiUrl} workspace={workspace} client-key={clientKey} placeholder={placeholder}></docslurp-search-box>
 <noscript><p>Enable JavaScript to search the document collection.</p></noscript>
 <script>
   import { defineDocSlurpSearch } from '@docslurp/sdk/widget';

package/README.md

@@ -10,13 +10,13 @@ import DocSlurpSearch from "@docslurp/contrib-astro";
 ---
 <!-- PUBLIC_DOCSLURP_CLIENT_KEY holds a browser key, safe to ship in page HTML. -->
 <DocSlurpSearch clientKey={import.meta.env.PUBLIC_DOCSLURP_CLIENT_KEY} />
-<!-- To search a named workspace: <DocSlurpSearch clientKey={...} workspaceId="product-manuals" /> -->
+<!-- To search a named workspace: <DocSlurpSearch clientKey={...} workspace="product-manuals" /> -->
 ```
 
 | Prop | Default | Notes |
 | --- | --- | --- |
 | `clientKey` | Required | A browser key: search-only and restricted to your allowed websites. Server keys are refused in the browser. |
-| `workspaceId` | `default` | A workspace slug (such as `product-manuals`), UUID or `default`, the key organization's default workspace. See [Workspaces](https://docslurp.io/docs/http#workspaces). |
+| `workspace` | `default` | A workspace ID, slug (such as `product-manuals`) or name, or `default`, the key organization's default workspace. See [Workspaces](https://docslurp.io/docs/http#workspaces). |
 | `apiUrl` | `https://docslurp.io` | The service origin. |
 | `placeholder` | `Search documents…` | Search box placeholder. |
 
@@ -38,28 +38,25 @@ Your server key is used only during the build. It never ends up in the generated
 import docslurpDocsIndex from '@docslurp/contrib-astro/build';
 
 integrations: [docslurpDocsIndex({
-  routes: ['/docs', '/docs/getting-started'], // List every public page to index.
+  routes: ['/docs', '/docs/getting-started'], // Every public page to index: lowercase paths under /docs.
   site: 'https://docs.example.com',           // Origin used for canonical page URLs.
   apiUrl: 'https://docslurp.io',
   apiKey: process.env.DOCSLURP_API_KEY,       // Server key with the ingest scope.
-  workspaceName: 'Product documentation',
-  // To add to an existing workspace instead: workspaceId: 'existing-workspace-slug',
+  workspace: 'Product documentation',          // ID, slug or name; created on the first build if none matches.
 })]
 ```
 
-Without `apiKey`, the build still writes `.docslurp/docs-index.json` and skips the upload. With a key, any indexing failure fails the build. A successful upload writes `docslurp-docs-search.json` to the client output with the workspace ID, so your search component can find it. Use `renderEnv` to pass environment variables that only the page renderer needs.
+Without `apiKey`, the build still writes `.docslurp/docs-index.json` and skips the upload. With a key, any indexing failure fails the build. A successful upload writes `docslurp-docs-search.json` (`{ "workspace": "<workspace ID>" }`) to the client output, so your search component can find it. Use `renderEnv` to pass environment variables that only the page renderer needs. `apiUrl` and `site` default to `https://docslurp.io` and `workspace` to `DocSlurp documentation`, so set `site` and `workspace` for your own docs.
 
 Pages are indexed as text: the upload asks for `{ visionFallback: false, preserveImages: false, summarize: true }`, so rendered HTML skips page images and vision and gets per-page summaries. Pass `pipeline` with other pipeline overrides to change that.
 
 To index a site after it deploys (for example when the build has no API key), crawl the live pages instead:
 
 ```bash
-DOCSLURP_API_KEY=... DOCSLURP_DOCS_WORKSPACE_ID=<workspace id> \
+DOCSLURP_API_KEY=... DOCSLURP_DOCS_WORKSPACE_ID=<workspace ID, slug or name> \
   node node_modules/@docslurp/contrib-astro/index-docs.mjs --site https://docs.example.com --routes routes.json --output .docslurp/docs-index.json
 ```
 
-`--routes` is a file or URL with a JSON array of paths. Only those paths on the site's own origin are fetched, and redirects are refused. Elements marked `data-search-exclude` (repeated boilerplate) are left out of the index.
+Set `DOCSLURP_URL` for a self-hosted service (default `https://docslurp.io`). `--routes` is a file or URL with a JSON array of `/docs` paths. Only those paths on the site's own origin are fetched, and redirects are refused. Elements marked `data-search-exclude` (repeated boilerplate) are left out of the index.
 
 This integration does not render protected pages, discover dynamic routes, delete documents for removed pages, or support other Astro adapters, so list your public documentation routes explicitly. Keep public documentation in its own organization, and use keys from that organization for both indexing and search.
-
-For how DocSlurp indexes its own website, see [Dogfood docs search](https://github.com/DocSlurp/docslurp-oss/blob/main/docs/docs-search.md).

package/build.mjs

@@ -2,7 +2,11 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 /** Index rendered Astro Node standalone pages through DocSlurp's public API. */
-export default function docslurpDocsIndex({ routes, apiKey, apiUrl = 'https://docslurp.io', workspaceId, workspaceName = 'DocSlurp documentation', site = 'https://docslurp.io', renderEnv = {}, pipeline }) {
+/**
+ * `workspace`: the workspace ID, slug or name to index into. A name that matches
+ * no workspace is created on the first build; later builds find it by name.
+ */
+export default function docslurpDocsIndex({ routes, apiKey, apiUrl = 'https://docslurp.io', workspace = 'DocSlurp documentation', site = 'https://docslurp.io', renderEnv = {}, pipeline }) {
   let root;
   return {
     name: '@docslurp/contrib-astro/docs-index',
@@ -15,7 +19,7 @@ export default function docslurpDocsIndex({ routes, apiKey, apiUrl = 'https://do
         await new Promise((resolve, reject) => {
           const child = spawn(process.execPath, [fileURLToPath(new URL('./index-docs.mjs', import.meta.url)), '--entry', fileURLToPath(entry), '--output', fileURLToPath(output), '--public-config', fileURLToPath(new URL('docslurp-docs-search.json', dir))], {
             cwd: fileURLToPath(root), stdio: 'inherit',
-            env: { ...process.env, ...renderEnv, ASTRO_NODE_AUTOSTART: 'disabled', DOCSLURP_API_KEY: apiKey ?? '', DOCSLURP_DOCS_INDEX_OPTIONS: JSON.stringify({ routes, apiUrl, workspaceId, workspaceName, site, ...(pipeline ? { pipeline } : {}) }) },
+            env: { ...process.env, ...renderEnv, ASTRO_NODE_AUTOSTART: 'disabled', DOCSLURP_API_KEY: apiKey ?? '', DOCSLURP_DOCS_INDEX_OPTIONS: JSON.stringify({ routes, apiUrl, workspace, site, ...(pipeline ? { pipeline } : {}) }) },
           });
           child.on('error', reject);
           child.on('exit', code => code === 0 ? resolve() : reject(new Error(`DocSlurp docs indexing exited with ${code}`)));

package/index-docs.mjs

@@ -59,20 +59,18 @@ export async function crawlDocs({ site, routes }, fetchImpl = fetch) {
  */
 export const DEFAULT_DOCS_PIPELINE = Object.freeze({ visionFallback: false, preserveImages: false, summarize: true });
 
-export async function indexDocs(corpus, { apiUrl, workspaceId, workspaceName, pipeline = DEFAULT_DOCS_PIPELINE }, apiKey, fetchImpl = fetch) {
+/**
+ * Uploads the rendered corpus into `workspace` (ID, slug or name): the server
+ * finds it, or creates a workspace with that name on the first build, so
+ * repeated builds keep landing in the same one.
+ */
+export async function indexDocs(corpus, { apiUrl, workspace = 'DocSlurp documentation', pipeline = DEFAULT_DOCS_PIPELINE }, apiKey, fetchImpl = fetch) {
   const base = apiUrl.replace(/\/$/, '');
   const request = async (path, init = {}) => {
     const response = await fetchImpl(`${base}${path}`, { ...init, headers: { ...init.headers, Authorization: `Bearer ${apiKey}` }, signal: AbortSignal.timeout(60_000) });
     if (!response.ok) throw new Error(`DocSlurp ${path}: HTTP ${response.status}`);
     return response.json();
   };
-  let target = workspaceId;
-  if (!target) {
-    const { workspaces } = await request('/v1/workspaces');
-    const matches = workspaces.filter(w => w.name === workspaceName);
-    if (matches.length > 1) throw new Error('Multiple docs workspaces: set DOCSLURP_DOCS_WORKSPACE_ID');
-    target = matches[0]?.id;
-  }
   const form = new FormData();
   const canonicalIds = [];
   for (const doc of corpus) {
@@ -81,10 +79,9 @@ export async function indexDocs(corpus, { apiUrl, workspaceId, workspaceName, pi
   }
   form.set('canonicalIds', JSON.stringify(canonicalIds));
   if (pipeline) form.set('pipeline', JSON.stringify(pipeline));
-  if (target) form.set('workspaceId', target);
-  else { form.set('newWorkspace', 'true'); form.set('workspaceName', workspaceName); }
-  const hash = createHash('sha256').update(JSON.stringify({ target: target ?? workspaceName, corpus, pipeline: pipeline ?? null })).digest('hex');
-  const result = await request('/v1/ingest/bulk', { method: 'POST', headers: { 'Idempotency-Key': `docs-${hash}` }, body: form });
+  form.set('workspace', workspace);
+  const hash = createHash('sha256').update(JSON.stringify({ target: workspace, corpus, pipeline: pipeline ?? null })).digest('hex');
+  const result = await request('/v1/uploads/bulk', { method: 'POST', headers: { 'Idempotency-Key': `docs-${hash}` }, body: form });
   const deadline = Date.now() + 10 * 60_000;
   while (Date.now() < deadline) {
     const { run } = await request(`/v1/runs/${encodeURIComponent(result.run.id)}/progress`);
@@ -98,7 +95,7 @@ export async function indexDocs(corpus, { apiUrl, workspaceId, workspaceName, pi
 async function main() {
   const args = process.argv.slice(2);
   const value = name => args[args.indexOf(name) + 1];
-  const options = { apiUrl: process.env.DOCSLURP_URL ?? 'https://docslurp.io', workspaceId: process.env.DOCSLURP_DOCS_WORKSPACE_ID || process.env.PUBLIC_DOCSLURP_DOCS_WORKSPACE_ID || undefined, workspaceName: 'DocSlurp documentation', ...(process.env.DOCSLURP_DOCS_PIPELINE ? { pipeline: JSON.parse(process.env.DOCSLURP_DOCS_PIPELINE) } : {}), ...JSON.parse(process.env.DOCSLURP_DOCS_INDEX_OPTIONS ?? '{}') };
+  const options = { apiUrl: process.env.DOCSLURP_URL ?? 'https://docslurp.io', workspace: process.env.DOCSLURP_DOCS_WORKSPACE_ID || process.env.PUBLIC_DOCSLURP_DOCS_WORKSPACE_ID || 'DocSlurp documentation', ...(process.env.DOCSLURP_DOCS_PIPELINE ? { pipeline: JSON.parse(process.env.DOCSLURP_DOCS_PIPELINE) } : {}), ...JSON.parse(process.env.DOCSLURP_DOCS_INDEX_OPTIONS ?? '{}') };
   const output = value('--output');
   let corpus;
   if (args.includes('--entry')) {
@@ -136,11 +133,11 @@ async function main() {
   if (key) {
     const indexed = await indexDocs(corpus, options, key);
     console.log('[docs-index]', indexed);
-    if (args.includes('--public-config')) await writeFile(value('--public-config'), JSON.stringify({ workspaceId: indexed.workspaceId }));
+    if (args.includes('--public-config')) await writeFile(value('--public-config'), JSON.stringify({ workspace: indexed.workspaceId }));
   }
   else {
     console.log('[docs-index] No API key; remote indexing skipped');
-    if (args.includes('--public-config')) await writeFile(value('--public-config'), JSON.stringify({ workspaceId: options.workspaceId ?? null }));
+    if (args.includes('--public-config')) await writeFile(value('--public-config'), JSON.stringify({ workspace: options.workspace ?? null }));
   }
 }
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docslurp/contrib-astro",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Astro search component for DocSlurp cited search, with a framework-free browser widget.",
   "license": "MIT",
   "homepage": "https://docslurp.io/docs/packages/contrib-astro",
@@ -27,7 +27,7 @@
     "index-docs.mjs"
   ],
   "dependencies": {
-    "@docslurp/sdk": "^0.3.0"
+    "@docslurp/sdk": "^0.4.0"
   },
   "publishConfig": {
     "access": "public"
@@ -35,6 +35,6 @@
   "scripts": {
     "build": "pnpm --filter @docslurp/sdk build",
     "typecheck": "pnpm --filter @docslurp/sdk typecheck",
-    "test": "node --test index-docs.test.mjs"
+    "test": "node ../../scripts/node-test.mjs index-docs.test.mjs"
   }
 }