Val Town Code SearchReturn to Val Town

31 */
32export const ZenithHashRequestSchema = z.object({
33  apiKey: z.string().min(1, "API key cannot be empty"),
34  username: z.string().min(1, "Username cannot be empty"),
35  password: z.string().min(1, "Password cannot be empty"),
60
61export const AuthenticatedZenithHashRequestSchema = z.object({
62  apiKey: z.string().min(1, "API key cannot be empty"),
63  username: z.string().optional(),
64  password: z.string().optional(),
128 *
129 * This endpoint helps clients generate the required fingerprint
130 * for Zenith Payments API integration without exposing credentials.
131 *
132 * The generated hash should be used as the 'fingerprint' field
456
457  // Create hash string according to Zenith format
458  const { apiKey, mode, paymentAmount, merchantUniquePaymentId, timestamp } = validatedData;
459  const hashString =
460    `${apiKey}|${username}|${password}|${mode}|${paymentAmount}|${merchantUniquePaymentId}|${timestamp}`;
461
462  // Get algorithm
530
531/**
532 * Generate hash using Web Crypto API
533 */
534async function generateHash(data: string, algorithm: string): Promise<string> {
547        break;
548      case "SHA3-512":
549        // SHA3-512 is not natively supported in Web Crypto API
550        // Try it first, fallback to SHA-512
551        try {
626      suggestion =
627        'Payment amount must be in cents/pence as whole numbers only. For $12.34, use "1234". For $100.00, use "10000".';
628    } else if (field === "apiKey") {
629      suggestion = "API key should be provided by Zenith Payments";
630    }
631
672
673  return await c.json({
674    purpose: "Generate fingerprint hash for Zenith Payments API",
675    endpoint: "/v1/hash",
676    current_time: currentTime,
699        description: "SHA-1 hash of concatenated fields",
700        algorithm: "SHA-1",
701        use_case: "Zenith API v3 integration",
702        warning: "SHA-1 is deprecated for security reasons, use v5",
703        example_request: {
704          apiKey: "test_api_key",
705          username: "merchant_user",
706          password: "merchant_pass",
715        description: "SHA-512 hash of concatenated fields",
716        algorithm: "SHA-512",
717        use_case: "Zenith API v4 integration (recommended by Zenith)",
718        example_request: {
719          apiKey: "test_api_key",
720          username: "merchant_user",
721          password: "merchant_pass",
732        use_case: "Most secure option for future compatibility",
733        example_request: {
734          apiKey: "test_api_key",
735          username: "merchant_user",
736          password: "merchant_pass",
745    v3_v4_v5_format: {
746      description: "Concatenated string format for hashing",
747      format: "apiKey|username|password|mode|paymentAmount|merchantUniquePaymentId|timestamp",
748      example: "test_api_key|merchant_user|merchant_pass|0|10050|INV-2025-001|2025-06-15T19:42:13Z",
749    },
750    required_fields: {
755      v3_v4_v5: {
756        public_access: [
757          "apiKey",
758          "username",
759          "password",
764        ],
765        authenticated_access: [
766          "apiKey",
767          "username (optional)",
768          "password (optional)",
786      },
787      authenticated_access: {
788        description: "Requires API key or session authentication",
789        benefit: "Username and password can use environment defaults if not provided in request",
790      },

2import type { HonoVariables as Variables } from "@/types/index.ts";
3import {
4  fetchFromFirecrawlAPI,
5  FirecrawlMapInput,
6  FirecrawlMapInputSchema,
7  performFirecrawlMap,
8  ScraperInput,
9  ScraperSchema,
10} from "../external-apis/firecrawlClient.ts";
11
12// Helper function to get error messages
24 * firecrawlScrape operation handler
25 * POST /v1/firecrawl/scrape
26 * Handles requests to the Firecrawl scrape API for a single URL.
27 */
28export async function firecrawlScrapeHandler(
50    const scrapeInput: ScraperInput = validationResult.data;
51
52    // Call the Firecrawl API through the client function
53    const firecrawlResponse = await fetchFromFirecrawlAPI(scrapeInput);
54
55    // Type assertion to ensure it's a valid JSON value
61
62    // Handle specific error cases
63    if (message.includes("Configuration error: invalid or missing FIRECRAWL_API_KEY")) {
64      return c.json({
65        success: false,
66        error: "Firecrawl API configuration error. Please contact support.",
67      }, 503); // Service Unavailable
68    }
71      return c.json({
72        success: false,
73        error: "Firecrawl API returned an error during scrape.",
74        details: error.message,
75      }, 502); // Bad Gateway
87 * firecrawlMap operation handler
88 * POST /v1/firecrawl/map
89 * Handles requests to the Firecrawl map API for discovering URLs on a website.
90 */
91export async function firecrawlMapHandler(c: Context<{ Variables: Variables }>): Promise<Response> {
93    const requestBody = await c.req.json();
94
95    // Validate the request body against the FirecrawlMapInputSchema
96    const validationResult = FirecrawlMapInputSchema.safeParse(requestBody);
97
98    if (!validationResult.success) {
106
107    // Use the validated data with explicit type
108    const mapInput: FirecrawlMapInput = validationResult.data;
109
110    // Call the dedicated map function with validated input
111    const firecrawlResponse = await performFirecrawlMap(mapInput);
112
113    // Type assertion to ensure it's a valid JSON value
119
120    // Handle specific error cases
121    if (message.includes("Configuration error: invalid or missing FIRECRAWL_API_KEY")) {
122      return c.json({
123        success: false,
124        error: "Firecrawl API configuration error. Please contact support.",
125      }, 503); // Service Unavailable
126    }
129      return c.json({
130        success: false,
131        error: "Firecrawl API returned an error during map operation.",
132        details: error.message,
133      }, 502); // Bad Gateway

1// F:\zApps\valtown.servers\APIServer\src\handlers\echo.service.ts
2import { getCurrentDateInSydney } from "@/utils/dateUtils.ts";
3

1/**
2 * callbackService.ts — Callback endpoint handlers for managing callback records with CRUD operations.
3 * Provides RESTful API for creating, listing, viewing, and deleting callback entries.
4 */
5

263/**
264 * Exchange Token - implements exchangeToken operation
265 * Converts API keys to JWT tokens for secure service access
266 */
267export async function exchangeToken(c: Context<{ Variables: Variables }>): Promise<Response> {
287    // Validate token key against configured keys
288    const validKeys = [
289      AUTH_CONFIG.methods.API_KEY.keys.internal,
290      AUTH_CONFIG.methods.API_KEY.keys.serviceToService,
291    ];
292
315    // Determine service type based on token key
316    let sourceService = "unknown-service";
317    let scope = "api:read";
318
319    if (tokenKey === AUTH_CONFIG.methods.API_KEY.keys.internal) {
320      sourceService = "internal-service";
321      scope = "internal-service api:read api:write";
322    } else if (tokenKey === AUTH_CONFIG.methods.API_KEY.keys.serviceToService) {
323      sourceService = "service-to-service";
324      scope = "s2s-service api:read api:write";
325    }
326
328    const jwtToken = await internalJwtService.generateInternalToken(c, {
329      sourceService,
330      targetEndpoint: "api-access",
331      scope,
332      expiryMinutes: 60, // 1 hour token
355        usage: {
356          header: "Authorization: Bearer " + jwtToken,
357          description: "Use this JWT token for API authentication",
358        },
359      },

1/**
2 * request-gateway.ts — Hono-based request gateway for the v2 API server.
3 * Now properly integrated with middleware chains for consistent request processing.
4 */
49
50/**
51 * OpenAPI Operation interface
52 */
53interface OpenAPIOperation {
54  operationId?: string;
55  summary?: string;
174
175  /**
176   * Register a handler for an OpenAPI operation ID
177   */
178  registerHandler(operationId: string, handler: RouteHandler): this {
217      case GatewayRouteType.BROWSER:
218      default:
219        return "/api/v1";
220    }
221  }
222
223  /**
224   * Register OpenAPI routes from specification
225   */
226  registerOpenApiRoutes(spec: any): this {
227    if (!spec.paths) return this;
228
233        }
234
235        const operation = operationData as OpenAPIOperation;
236        const operationId = operation.operationId;
237        if (!operationId) continue;
243        }
244
245        // Determine route type from OpenAPI extensions or path
246        const routeType = this.determineRouteType(path, operation);
247
248        // Convert OpenAPI path to Hono path format
249        const honoPath = path.replace(/\{([^}]+)\}/g, ":$1");
250
272   * Determine route type from path and operation
273   */
274  private determineRouteType(path: string, operation: OpenAPIOperation): GatewayRouteType {
275    // Check OpenAPI extensions first
276    if (operation["x-route-type"]) {
277      return operation["x-route-type"] as GatewayRouteType;
294
295  /**
296   * Extract authentication requirement from OpenAPI operation
297   */
298  private extractAuthRequirement(operation: OpenAPIOperation): AuthMethod {
299    if (!operation.security || operation.security.length === 0) {
300      return "none";
306
307    if (securitySchemes.includes("bearerAuth")) return "jwt";
308    if (securitySchemes.includes("apiKey")) return "apiKey";
309    if (securitySchemes.includes("oauth2")) return "oauth";
310    if (securitySchemes.includes("basicAuth")) return "basic";
370   */
371  serve(port = 8000): void {
372    console.log(`🚀 API Gateway starting on port ${port}`);
373    console.log(`📚 API Documentation: ${APP_CONFIG.server.BASE_URL}/docs`);
374    console.log(`🔗 API Base URL: ${APP_CONFIG.server.BASE_URL}/api/v1`);
375    console.log("");
376    console.log("Middleware chains configured:");

1/**
2 * tavily-client.ts - Tavily API integration client for v2
3 */
4
5import { z } from "z";
6
7// --- Tavily Search Schema (based on actual API documentation) ---
8export const TavilySearchSchema = z.object({
9  query: z.string().min(1, "Search query cannot be empty"),
31export type TavilySearchInput = z.infer<typeof TavilySearchSchema>;
32
33// --- Tavily Extract Schema (based on actual API documentation) ---
34export const TavilyExtractSchema = z.object({
35  urls: z.union([
45export type TavilyExtractInput = z.infer<typeof TavilyExtractSchema>;
46
47// --- Tavily Crawl Schema (based on actual API documentation) ---
48export const TavilyCrawlInputSchema = z.object({
49  url: z.string().url("Root URL to begin crawling is required"),
76export type TavilyCrawlInput = z.infer<typeof TavilyCrawlInputSchema>;
77
78// --- Tavily Map Schema (based on actual API documentation) ---
79export const TavilyMapInputSchema = z.object({
80  url: z.string().url("Root URL to begin mapping is required"),
81  max_depth: z.number().int().min(1).optional().default(1),
101});
102
103export type TavilyMapInput = z.infer<typeof TavilyMapInputSchema>;
104
105// API configuration
106function getTavilyApiKey(): string {
107  const key = Deno.env.get("TAVILY_API_KEY") || "";
108  if (!key) {
109    throw new Error("Configuration error: invalid or missing TAVILY_API_KEY");
110  }
111  return key;
112}
113
114const TAVILY_API_BASE_URL = "https://api.tavily.com";
115
116/**
117 * Perform a search using the Tavily API.
118 */
119export async function performTavilySearch(input: TavilySearchInput): Promise<unknown> {
120  const apiKey = getTavilyApiKey();
121  const options = {
122    method: "POST",
123    headers: {
124      "Authorization": `Bearer ${apiKey}`,
125      "Content-Type": "application/json",
126    },
128  };
129
130  const response = await fetch(`${TAVILY_API_BASE_URL}/search`, options);
131
132  if (!response.ok) {
136    } catch {
137      console.error(
138        `Failed to parse error response from Tavily API for search: ${response.status} - ${response.statusText}`,
139      );
140    }
146
147/**
148 * Perform an extract using the Tavily API.
149 */
150export async function performTavilyExtract(input: TavilyExtractInput): Promise<unknown> {
151  const apiKey = getTavilyApiKey();
152
153  // Ensure urls is always an array for the API
154  const apiInput = {
155    ...input,
156    urls: Array.isArray(input.urls) ? input.urls : [input.urls],
160    method: "POST",
161    headers: {
162      "Authorization": `Bearer ${apiKey}`,
163      "Content-Type": "application/json",
164    },
165    body: JSON.stringify(apiInput),
166  };
167
168  const response = await fetch(`${TAVILY_API_BASE_URL}/extract`, options);
169
170  if (!response.ok) {
174    } catch {
175      console.error(
176        `Failed to parse error response from Tavily API for extract: ${response.status} - ${response.statusText}`,
177      );
178    }
184
185/**
186 * Perform a crawl using the Tavily API (BETA).
187 */
188export async function performTavilyCrawl(input: TavilyCrawlInput): Promise<unknown> {
189  const apiKey = getTavilyApiKey();
190
191  // Convert empty arrays to null as per API documentation
192  const apiInput = {
193    ...input,
194    select_paths: input.select_paths?.length ? input.select_paths : null,
202    method: "POST",
203    headers: {
204      "Authorization": `Bearer ${apiKey}`,
205      "Content-Type": "application/json",
206    },
207    body: JSON.stringify(apiInput),
208  };
209
210  const response = await fetch(`${TAVILY_API_BASE_URL}/crawl`, options);
211
212  if (!response.ok) {
216    } catch {
217      console.error(
218        `Failed to parse error response from Tavily API for crawl: ${response.status} - ${response.statusText}`,
219      );
220    }
226
227/**
228 * Perform a site map using the Tavily API (BETA).
229 */
230export async function performTavilyMap(input: TavilyMapInput): Promise<unknown> {
231  const apiKey = getTavilyApiKey();
232
233  // Convert empty arrays to null as per API documentation
234  const apiInput = {
235    ...input,
236    select_paths: input.select_paths?.length ? input.select_paths : null,
244    method: "POST",
245    headers: {
246      "Authorization": `Bearer ${apiKey}`,
247      "Content-Type": "application/json",
248    },
249    body: JSON.stringify(apiInput),
250  };
251
252  const response = await fetch(`${TAVILY_API_BASE_URL}/map`, options);
253
254  if (!response.ok) {
258    } catch {
259      console.error(
260        `Failed to parse error response from Tavily API for map: ${response.status} - ${response.statusText}`,
261      );
262    }

1// Future implementation of OpenAI client for API calls
2import { OpenAI } from "openai";
3
4const openai = new OpenAI({
5  apiKey: Deno.env.get("OPENAI_API_KEY"),
6});
7

1// F:\zApps\valtown.servers\APIServer\src\external-apis\firecrawl-client.ts
2
3import FirecrawlApp from "firecrawl";
94export type ScraperInput = z.infer<typeof ScraperSchema>;
95
96// Map schema - Based on actual Firecrawl API documentation
97export const FirecrawlMapInputSchema = z.object({
98  url: z.string().url("Invalid URL format"),
99  search: z.string().optional(),
105});
106
107export type FirecrawlMapInput = z.infer<typeof FirecrawlMapInputSchema>;
108
109function getApiKey(): string {
110  const key = Deno.env.get("FIRECRAWL_API_KEY") || "";
111  if (!key) {
112    throw new Error("Configuration error: invalid or missing FIRECRAWL_API_KEY");
113  }
114  return key;
116
117function getFirecrawlClient(): FirecrawlApp {
118  const apiKey = getApiKey();
119  return new FirecrawlApp({ apiKey });
120}
121
122/**
123 * Fetch content via the Firecrawl API scrape endpoint.
124 * Handles single page scraping with all supported options.
125 */
126export async function fetchFromFirecrawlAPI(
127  input: ScraperInput,
128): Promise<unknown> {
170
171/**
172 * Perform a map operation using the Firecrawl API.
173 * Maps all URLs from a website using Firecrawl's dedicated map endpoint.
174 */
175export async function performFirecrawlMap(
176  input: FirecrawlMapInput,
177): Promise<unknown> {
178  const firecrawl = getFirecrawlClient();
181    // Use the dedicated map method from FirecrawlApp
182    // Note: The FirecrawlApp SDK might need to be updated to support the map endpoint
183    // If the SDK doesn't have a map method, we'll need to make a direct API call
184
185    // Check if FirecrawlApp has a map method
195      });
196    } else {
197      // Fallback to direct API call if SDK doesn't support map
198      const apiKey = getApiKey();
199      const response = await fetch("https://api.firecrawl.dev/v1/map", {
200        method: "POST",
201        headers: {
202          "Authorization": `Bearer ${apiKey}`,
203          "Content-Type": "application/json",
204        },
212        } catch {
213          console.error(
214            `Failed to parse error response from Firecrawl API for map: ${response.status} - ${response.statusText}`,
215          );
216        }

13
14// Documentation services - Updated to use handler functions
15import { getOpenAPIJSON, getOpenAPIYAML } from "../handlers/openapiService.ts";
16import { getSwaggerUI } from "../handlers/swaggerService.ts";
17import { getRedoc } from "../handlers/redoclyService.ts";
21import { proxyGetHandler, proxyPostHandler } from "../handlers/proxyService.ts";
22
23// External API services
24import {
25  tavilyCrawlHandler,
27  tavilyMapHandler,
28  tavilySearchHandler,
29} from "../handlers/tavilyApiService.ts";
30import { firecrawlMapHandler, firecrawlScrapeHandler } from "../handlers/firecrawlApiService.ts";
31import { getApiInfo, getVersion } from "../handlers/infoService.ts";
32import { getHash } from "../handlers/hashService.ts";
33
84
85    // === Documentation Handlers - Now using imported functions ===
86    getOpenAPIJSON,
87    getOpenAPIYAML,
88    getSwaggerUI,
89    getRedoc,
95    proxyPost: proxyPostHandler,
96
97    // === External API Handlers ===
98    tavilySearch: tavilySearchHandler,
99    tavilyExtract: tavilyExtractHandler,
104
105    // Info and Version Handlers (Implemented)
106    getApiInfo,
107    getVersion,
108
191      "handleSpotifyCallback",
192    ],
193    "Documentation": ["getOpenAPIJSON", "getOpenAPIYAML", "getSwaggerUI", "getRedoc"],
194    "Utility (Echo)": ["echoGet", "echoPost"],
195    "Utility (Proxy)": ["proxyGet", "proxyPost"],
196    "External API (Tavily)": ["tavilySearch", "tavilyExtract", "tavilyCrawl", "tavilyMap"],
197    "External API (Firecrawl)": ["firecrawlScrape", "firecrawlMap"],
198    "Info": ["getApiInfo", "getVersion"],
199  };
200