Val Town Code SearchReturn to Val Town

1/**
2 * openapi.service.ts - Serves the OpenAPI specification.
3 * Uses OpenAPILoader to get the fully resolved specification.
4 */
5
6import { stringify } from "yaml";
7import { loadOpenAPISpec } from "@/openapi/loader.ts";
8import { getCurrentDateInSydney } from "@/utils/dateUtils.ts";
9import { Context } from "hono";
30}
31
32interface OpenAPIDocument {
33  openapi: string;
34  info: any;
35  servers: any[];
37  components: any;
38  // Adding an index signature to make it compatible with yaml.stringify
39  // and to acknowledge that OpenAPI documents can have various other top-level extension fields.
40  [key: string]: any;
41}
42
43export class OpenapiSpecService {
44  private openapiSpecPromise: Promise<OpenAPIDocument> | null = null;
45  private readonly rootPath: string;
46
47  constructor(rootPath: string) {
48    this.rootPath = rootPath;
49    this.openapiSpecPromise = loadOpenAPISpec(this.rootPath) as Promise<OpenAPIDocument>;
50  }
51
52  private async getSpec(): Promise<OpenAPIDocument> {
53    if (!this.openapiSpecPromise) {
54      console.warn(
55        "OpenapiSpecService: Spec promise not initialized or failed, attempting to load now.",
56      );
57      this.openapiSpecPromise = loadOpenAPISpec(this.rootPath) as Promise<OpenAPIDocument>;
58    }
59    try {
60      const spec = await this.openapiSpecPromise;
61      if (!spec) { // Check if the loaded spec is null or undefined
62        throw new Error("Loaded OpenAPI specification is null or undefined.");
63      }
64      return spec;
65    } catch (error: unknown) {
66      const message = getErrorMessage(error);
67      console.error("OpenapiSpecService: Failed to load/get OpenAPI spec:", error); // Log the original error too
68      this.openapiSpecPromise = null; // Clear the promise so it can be retried
69      throw new Error(`Failed to load OpenAPI specification: ${message}`);
70    }
71  }
72
73  async getOpenAPIJSONObject(): Promise<OpenAPIDocument> {
74    return await this.getSpec();
75  }
76
77  async getOpenAPIYAMLString(): Promise<string> {
78    try {
79      const jsonSpec = await this.getSpec();
80      // The OpenAPIDocument with an index signature [key: string]: any;
81      // should now be compatible with stringify.
82      return stringify(jsonSpec);
83    } catch (error: unknown) {
84      const message = getErrorMessage(error);
85      console.error("OpenapiSpecService: Failed to generate OpenAPI YAML:", error);
86      throw new Error(`Failed to generate OpenAPI YAML specification: ${message}`);
87    }
88  }
93      error: errorMessage,
94      format,
95      service: "openapi-spec-service",
96      timestamp: getCurrentDateInSydney(),
97    };
106      return {
107        valid: false,
108        error: `OpenAPI spec validation failed: ${message}`,
109      };
110    }
112}
113
114export const openapiSpecService = new OpenapiSpecService("src/openapi/spec");
115
116/**
117 * OpenAPI JSON handler function for use in service router
118 * @param c - Hono context with Variables
119 * @returns Response with OpenAPI JSON specification
120 */
121export async function getOpenAPIJSON(c: Context<{ Variables: Variables }>): Promise<Response> {
122  try {
123    const spec = await openapiSpecService.getOpenAPIJSONObject();
124    return c.json(spec);
125  } catch (error) {
126    const msg = getErrorMessage(error);
127    console.error(`Error in getOpenAPIJSON: ${msg}`, error);
128    return c.json(openapiSpecService.createErrorResponse(msg, "json"), 500);
129  }
130}
131
132/**
133 * OpenAPI YAML handler function for use in service router
134 * @param c - Hono context with Variables
135 * @returns Response with OpenAPI YAML specification
136 */
137export async function getOpenAPIYAML(c: Context<{ Variables: Variables }>): Promise<Response> {
138  try {
139    const yamlString = await openapiSpecService.getOpenAPIYAMLString();
140    c.res.headers.set("Content-Type", "application/yaml; charset=utf-8");
141    return c.text(yamlString);
142  } catch (error) {
143    const msg = getErrorMessage(error);
144    console.error(`Error in getOpenAPIYAML: ${msg}`, error);
145    return c.json(openapiSpecService.createErrorResponse(msg, "yaml"), 500);
146  }
147}

1/**
2 * spotify.auth.service.ts — Spotify OAuth authentication service handlers.
3 * Implements OpenAPI operations using existing middleware and services.
4 */
5
292async function fetchSpotifyUserInfo(accessToken: string) {
293  try {
294    const userRequest = await fetch("https://api.spotify.com/v1/me", {
295      headers: {
296        "Authorization": `Bearer ${accessToken}`,

1// F:\zApps\valtown.servers\APIServer\src\handlers\oauth\index.ts
2
3export { getGoogleOAuthURL, handleGoogleCallback } from "./googleAuthService.ts";

1// F:\zApps\valtown.servers\APIServer\src\handlers\oauth\google.auth.service.ts
2/**
3 * auth.service.ts — OAuth authentication service handlers.
4 * Implements OpenAPI operations using existing middleware and services.
5 */
6

1// F:\zApps\valtown.servers\APIServer\src\handlers\oauth\github.auth.service.ts
2/**
3 * github.auth.service.ts — GitHub OAuth authentication service handlers.
4 * Implements OpenAPI operations using existing middleware and services.
5 */
6
296        "Authorization": `Bearer ${accessToken}`,
297        "Accept": "application/vnd.github.v3+json",
298        "User-Agent": "Val.town-API-Server/2.0",
299      },
300    });
348async function fetchGitHubUserEmail(accessToken: string) {
349  try {
350    const emailRequest = await fetch("https://api.github.com/user/emails", {
351      headers: {
352        "Authorization": `Bearer ${accessToken}`,
353        "Accept": "application/vnd.github.v3+json",
354        "User-Agent": "Val.town-API-Server/2.0",
355      },
356    });

4
5// You can store these in environment variables or a config file
6const API_VERSION = Deno.env.get("API_VERSION") || "1.0.0";
7const API_BUILD = Deno.env.get("API_BUILD") || "unknown";
8const API_ENV = Deno.env.get("API_ENV") || "development";
9
10/**
11 * Service for providing API information and version details
12 */
13export class InfoService {
14  /**
15   * Get basic API information
16   * @returns API info object with status and basic metadata
17   */
18  getApiInfo() {
19    return {
20      success: true,
21      name: "ValTown API Server",
22      version: API_VERSION,
23      status: "operational",
24      environment: API_ENV,
25      timestamp: getCurrentDateInSydney(),
26      uptime: null, // Note: Deno doesn't have process.uptime()
29          swagger: "/v1/docs",
30          redoc: "/v1/redoc",
31          openapi: "/v1/openapi.json",
32        },
33        external: {
47      success: true,
48      version: {
49        api: API_VERSION,
50        build: API_BUILD,
51        environment: API_ENV,
52        node: Deno.version.deno,
53        v8: Deno.version.v8,
85
86/**
87 * API info handler function for use in service router
88 * @param c - Hono context with Variables
89 * @returns Response with API information
90 */
91export function getApiInfo(c: Context<{ Variables: Variables }>): Response {
92  try {
93    const info = infoService.getApiInfo();
94    return c.json(info);
95  } catch (error) {
96    const errorResponse = infoService.createErrorResponse(
97      error instanceof Error ? error.message : "Failed to retrieve API information",
98    );
99    return c.json(errorResponse, 500);

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      },

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