@gitbook/react-openapi 1.3.6 → 1.4.0

package/src/util/tryit-prefill.test.ts

@@ -0,0 +1,311 @@
+import { describe, expect, it } from 'bun:test';
+import type { PrefillInputContextData } from '../OpenAPIPrefillContextProvider';
+import type { OpenAPIOperationData } from '../types';
+import { resolveTryItPrefillForOperation } from './tryit-prefill';
+
+describe('resolveTryItPrefillForOperation', () => {
+    describe('prefill authentication info', () => {
+        it('should resolve prefill for bearer token scheme', () => {
+            const operation: OpenAPIOperationData = {
+                path: '/orgs/<orgId>/spaces/<spaceId>',
+                method: 'GET',
+                operation: { summary: 'Get space by ID' },
+                servers: [{ url: 'https://api.gitbook.com/v1/' }],
+                securities: [
+                    [
+                        'apiTokenScheme',
+                        {
+                            type: 'http',
+                            scheme: 'bearer',
+                            'x-gitbook-prefill': '{{ visitor.claims.apiToken }}',
+                        },
+                    ],
+                ],
+            };
+
+            const prefillInputContext: PrefillInputContextData = {
+                visitor: { claims: { apiToken: 'gb_api_testToken' } },
+            };
+
+            const result = resolveTryItPrefillForOperation({
+                operation,
+                prefillInputContext,
+            });
+
+            expect(result).toEqual({
+                authentication: {
+                    securitySchemes: {
+                        apiTokenScheme: { token: 'gb_api_testToken' },
+                    },
+                },
+            });
+        });
+
+        it('should resolve prefill for basic auth scheme', () => {
+            const operation: OpenAPIOperationData = {
+                path: '/orgs/<orgId>/spaces',
+                method: 'PUT',
+                operation: { summary: 'Create space in an org' },
+                servers: [{ url: 'https://api.gitbook.com/v1/' }],
+                securities: [
+                    [
+                        'basicAuthScheme',
+                        {
+                            type: 'http',
+                            scheme: 'basic',
+                            'x-gitbook-prefill': '{{ visitor.claims.basicAuth }}',
+                        },
+                    ],
+                ],
+            };
+
+            const prefillInputContext: PrefillInputContextData = {
+                visitor: { claims: { basicAuth: 'testuser:testpassword' } },
+            };
+
+            const result = resolveTryItPrefillForOperation({
+                operation,
+                prefillInputContext,
+            });
+
+            expect(result).toEqual({
+                authentication: {
+                    securitySchemes: {
+                        basicAuthScheme: { username: 'testuser', password: 'testpassword' },
+                    },
+                },
+            });
+        });
+
+        it('should resolve prefill for apiKey scheme', () => {
+            const operation: OpenAPIOperationData = {
+                path: '/orgs/<orgId>/spaces/<spaceId>',
+                method: 'POST',
+                operation: { summary: 'Update space by ID' },
+                servers: [{ url: 'https://api.gitbook.com/v1/' }],
+                securities: [
+                    [
+                        'apiKeyHeader',
+                        {
+                            type: 'apiKey',
+                            in: 'header',
+                            name: 'X-API-KEY',
+                            'x-gitbook-prefill': '{{ visitor.claims.apiKey }}',
+                        },
+                    ],
+                ],
+            };
+
+            const prefillInputContext: PrefillInputContextData = {
+                visitor: { claims: { apiKey: 'key-123' } },
+            };
+
+            const result = resolveTryItPrefillForOperation({
+                operation,
+                prefillInputContext,
+            });
+
+            expect(result).toEqual({
+                authentication: {
+                    securitySchemes: {
+                        apiKeyHeader: { name: 'X-API-KEY', in: 'header', value: 'key-123' },
+                    },
+                },
+            });
+        });
+
+        it('should return empty object if no visitor data matches prefill expression', () => {
+            const operation: OpenAPIOperationData = {
+                path: '/orgs/<orgId>/spaces',
+                method: 'GET',
+                operation: { summary: 'List all spaces in an org' },
+                servers: [{ url: 'https://api.gitbook.com/v1/' }],
+                securities: [
+                    [
+                        'bearer',
+                        {
+                            type: 'http',
+                            scheme: 'bearer',
+                            'x-gitbook-prefill': '{{ visitor.claims.missing }}',
+                        },
+                    ],
+                ],
+            };
+
+            const prefillInputContext: PrefillInputContextData = {
+                visitor: { claims: {} },
+            };
+
+            const result = resolveTryItPrefillForOperation({
+                operation,
+                prefillInputContext,
+            });
+
+            expect(result).toEqual({});
+        });
+    });
+
+    describe('prefill server info', () => {
+        it('should prefill server at url level', () => {
+            const operation: OpenAPIOperationData = {
+                path: '/orgs/<orgId>/spaces',
+                method: 'GET',
+                operation: { summary: 'List spaces in an org' },
+                servers: [
+                    {
+                        url: 'https://api.gitbook.com/v1/',
+                        description: 'GitBook API endpoint',
+                        'x-gitbook-prefill': '{{ visitor.claims.api.endpointUrl }}',
+                    },
+                ],
+                securities: [],
+            };
+
+            const prefillInputContext: PrefillInputContextData = {
+                visitor: {
+                    claims: { api: { endpointUrl: 'https://api.gitbook-staging.com/v1/' } },
+                },
+            };
+
+            const result = resolveTryItPrefillForOperation({
+                operation,
+                prefillInputContext,
+            });
+
+            expect(result).toEqual({
+                servers: [
+                    {
+                        url: 'https://api.gitbook-staging.com/v1/',
+                        description: 'GitBook API endpoint',
+                    },
+                ],
+            });
+        });
+
+        it('should prefill server at variables level', () => {
+            const operation: OpenAPIOperationData = {
+                path: '/orgs/<orgId>/spaces',
+                method: 'GET',
+                operation: { summary: 'List spaces in an org' },
+                servers: [
+                    {
+                        url: 'https://api.{domain}/{version}/',
+                        description: 'Versioned API endpoint by environment',
+                        variables: {
+                            domain: {
+                                default: 'gitbook.com',
+                                'x-gitbook-prefill':
+                                    '{{ visitor.claims.api.env === "staging" ?  "gitbook-staging.com" : "gitbook.com" }}',
+                            },
+                            version: {
+                                default: 'v1',
+                                'x-gitbook-prefill': '{{ visitor.claims.api.version }}',
+                            },
+                        },
+                    },
+                ],
+                securities: [],
+            };
+
+            // Override env
+            const overrideEnvResult = resolveTryItPrefillForOperation({
+                operation,
+                prefillInputContext: { visitor: { claims: { api: { env: 'staging' } } } },
+            });
+            expect(overrideEnvResult).toEqual({
+                servers: [
+                    {
+                        url: 'https://api.{domain}/{version}/',
+                        description: 'Versioned API endpoint by environment',
+                        variables: {
+                            domain: { default: 'gitbook-staging.com' },
+                            version: { default: 'v1' },
+                        },
+                    },
+                ],
+            });
+
+            // Override version
+            const overrideVersionResult = resolveTryItPrefillForOperation({
+                operation,
+                prefillInputContext: { visitor: { claims: { api: { version: 'v2' } } } },
+            });
+            expect(overrideVersionResult).toEqual({
+                servers: [
+                    {
+                        url: 'https://api.{domain}/{version}/',
+                        description: 'Versioned API endpoint by environment',
+                        variables: {
+                            domain: { default: 'gitbook.com' },
+                            version: { default: 'v2' },
+                        },
+                    },
+                ],
+            });
+
+            // Override both
+            const overrideBoth = resolveTryItPrefillForOperation({
+                operation,
+                prefillInputContext: {
+                    visitor: { claims: { api: { env: 'staging', version: 'v2' } } },
+                },
+            });
+            expect(overrideBoth).toEqual({
+                servers: [
+                    {
+                        url: 'https://api.{domain}/{version}/',
+                        description: 'Versioned API endpoint by environment',
+                        variables: {
+                            domain: { default: 'gitbook-staging.com' },
+                            version: { default: 'v2' },
+                        },
+                    },
+                ],
+            });
+        });
+
+        it('should ignore server prefill when no matching visitor data', () => {
+            const operation: OpenAPIOperationData = {
+                path: '/orgs/<orgId>/spaces',
+                method: 'GET',
+                operation: { summary: 'List spaces in an org' },
+                servers: [
+                    {
+                        url: 'https://api.{domain}/{version}/',
+                        description: 'Versioned API endpoint by environment',
+                        variables: {
+                            domain: {
+                                default: 'gitbook.com',
+                                'x-gitbook-prefill':
+                                    '{{ visitor.claims.api.env === "staging" ?  "gitbook-staging.com" : "gitbook.com" }}',
+                            },
+                            version: {
+                                default: 'v1',
+                                'x-gitbook-prefill': '{{ visitor.claims.api.version }}',
+                            },
+                        },
+                    },
+                ],
+                securities: [],
+            };
+
+            const result = resolveTryItPrefillForOperation({
+                operation,
+                prefillInputContext: { visitor: { claims: { isBetaUser: true } } },
+            });
+
+            expect(result).toEqual({
+                servers: [
+                    {
+                        url: 'https://api.{domain}/{version}/',
+                        description: 'Versioned API endpoint by environment',
+                        variables: {
+                            domain: { default: 'gitbook.com' },
+                            version: { default: 'v1' },
+                        },
+                    },
+                ],
+            });
+        });
+    });
+});

package/src/util/tryit-prefill.ts

@@ -0,0 +1,156 @@
+import { ExpressionRuntime, parseTemplate } from '@gitbook/expr';
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import type { ApiClientConfiguration } from '@scalar/types';
+import type { PrefillInputContextData } from '../OpenAPIPrefillContextProvider';
+import type { OpenAPIOperationData } from '../types';
+
+export interface TryItPrefillConfiguration {
+    authentication?: ApiClientConfiguration['authentication'];
+    servers?: ApiClientConfiguration['servers'];
+}
+
+/**
+ * Resolve the Scalar API client prefill configuration for a given OpenAPI operation.
+ */
+export function resolveTryItPrefillForOperation(args: {
+    /**
+     * The parsed OpenAPI operation.
+     */
+    operation: Pick<OpenAPIOperationData, 'securities' | 'servers'>;
+    /**
+     * Prefill input context data.
+     */
+    prefillInputContext: PrefillInputContextData | null;
+}): TryItPrefillConfiguration {
+    const {
+        operation: { securities, servers },
+        prefillInputContext,
+    } = args;
+
+    // Fixed ExpressionRuntime and resolveTryItPrefillExpression function
+    const runtime = new ExpressionRuntime();
+    const resolveTryItPrefillExpression = (expr: string) => {
+        if (!prefillInputContext) return undefined;
+        const parts = parseTemplate(expr);
+        if (!parts.length) return undefined;
+        return runtime.evaluateTemplate(expr, prefillInputContext);
+    };
+
+    const prefillAuth = securities
+        ? resolveTryItPrefillAuthForOperationSecurities({
+              securities,
+              resolveTryItPrefillExpression,
+          })
+        : undefined;
+
+    const prefillServers = servers
+        ? resolveTryItPrefillServersForOperationServers({ servers, resolveTryItPrefillExpression })
+        : [];
+
+    return {
+        ...(prefillAuth ? { authentication: prefillAuth } : {}),
+        ...(prefillServers ? { servers: prefillServers } : {}),
+    };
+}
+
+/**
+ * Resolve prefill authentication configuration for the security schemes defined for an operation.
+ */
+function resolveTryItPrefillAuthForOperationSecurities(args: {
+    securities: OpenAPIOperationData['securities'];
+    resolveTryItPrefillExpression: (expr: string) => string | undefined;
+}): ApiClientConfiguration['authentication'] | undefined {
+    const { securities, resolveTryItPrefillExpression } = args;
+    const prefillAuthConfig: ApiClientConfiguration['authentication']['securitySchemes'] = {};
+
+    for (const [schemeName, security] of Object.values(securities)) {
+        const tryitPrefillAuthValue = security['x-gitbook-prefill']
+            ? resolveTryItPrefillExpression(security['x-gitbook-prefill'])
+            : undefined;
+
+        if (!tryitPrefillAuthValue) {
+            continue;
+        }
+
+        switch (security.type) {
+            case 'http': {
+                if (security.scheme?.includes('bearer')) {
+                    prefillAuthConfig[schemeName] = { token: tryitPrefillAuthValue };
+                } else if (
+                    security.scheme?.includes('basic') &&
+                    tryitPrefillAuthValue.includes(':')
+                ) {
+                    const [username, password] = tryitPrefillAuthValue.split(':', 2);
+                    prefillAuthConfig[schemeName] = { username, password };
+                }
+                break;
+            }
+            case 'apiKey': {
+                prefillAuthConfig[schemeName] = {
+                    name: security.name,
+                    in: security.in,
+                    value: tryitPrefillAuthValue,
+                };
+                break;
+            }
+            case 'oauth2':
+            case 'openIdConnect': {
+                break;
+            }
+        }
+    }
+
+    return Object.keys(prefillAuthConfig).length > 0
+        ? { securitySchemes: prefillAuthConfig }
+        : undefined;
+}
+
+/**
+ * Resolve prefill server configuration for the servers defined for an operation.
+ */
+function resolveTryItPrefillServersForOperationServers(args: {
+    servers: OpenAPIOperationData['servers'];
+    resolveTryItPrefillExpression: (expr: string) => string | undefined;
+}): ApiClientConfiguration['servers'] | undefined {
+    const { servers, resolveTryItPrefillExpression } = args;
+    const resolvedServers: ApiClientConfiguration['servers'] = [];
+
+    for (const server of servers) {
+        // Url-level prefill
+        const tryItPrefillServerUrlExpr = server['x-gitbook-prefill'];
+        const tryItPrefillServerUrlValue = tryItPrefillServerUrlExpr
+            ? resolveTryItPrefillExpression(tryItPrefillServerUrlExpr)
+            : undefined;
+
+        const variables: { [variable: string]: OpenAPIV3.ServerVariableObject } = server.variables
+            ? { ...server.variables }
+            : {};
+
+        // Variable-level prefill
+        if (server.variables) {
+            for (const [varName, variable] of Object.entries(server.variables)) {
+                const { 'x-gitbook-prefill': tryItPrefillVarExpr, ...variableProps } = variable;
+
+                const tryItPrefillVarValue = tryItPrefillVarExpr
+                    ? resolveTryItPrefillExpression(tryItPrefillVarExpr)
+                    : undefined;
+                variables[varName] = {
+                    ...variableProps,
+                    ...(tryItPrefillVarValue ? { default: String(tryItPrefillVarValue) } : {}),
+                };
+            }
+        }
+
+        const hasServerVariables = Object.keys(variables).length > 0;
+        if (server.url && (tryItPrefillServerUrlValue || hasServerVariables)) {
+            const resolvedServer: OpenAPIV3.ServerObject = {
+                url: tryItPrefillServerUrlValue ?? server.url,
+                ...(server.description ? { description: server.description } : {}),
+                ...(hasServerVariables ? { variables } : {}),
+            };
+            resolvedServers.push(resolvedServer);
+        }
+    }
+
+    return resolvedServers.length > 0 ? resolvedServers : undefined;
+}