Val Town Code SearchReturn to Val Town

1// F:\zApps\valtown.servers\APIServer\src\config\header.config.ts
2import type {
3  CorsConfig,
25    "Authorization",
26    "X-CSRF-Token",
27    "X-API-Key",
28    "X-Requested-With",
29    "Origin",
51      "https://unpkg.com",
52    ],
53    "style-src": ["'self'", "'unsafe-inline'", "https://fonts.googleapis.com"],
54    "img-src": ["'self'", "data:", "https:", "blob:"],
55    "font-src": ["'self'", "https://fonts.gstatic.com"],
56    "connect-src": ["'self'", "https://api.val.town", "wss://ws.val.town", "https://*.sentry.io"],
57    "frame-src": ["'none'"],
58    "frame-ancestors": ["'none'"],
193    enabled: true,
194    headers: {
195      "X-API-Version": "2.0.0",
196      "X-Service": "Val.town API",
197      "X-Response-Time": "0",
198    },

1/**
2 * controller.registry.ts — OpenAPI controller to handler mapping system.
3 * Maps x-controller and x-method extensions to actual TypeScript handlers.
4 */
7
8/**
9 * Handler function signature for all API endpoints
10 */
11export type HandlerFunction = (c: Context) => Promise<Response> | Response;
40  },
41  external: {
42    module: "@/handlers/external-api.service.ts",
43    methods: {
44      tavilySearch: "tavilySearch",
67      getSwaggerUI: "getSwaggerUI",
68      getRedocUI: "getRedocUI",
69      getOpenApiJson: "getOpenApiJson",
70      getOpenApiYaml: "getOpenApiYaml",
71    },
72  },
95
96  /**
97   * Resolve handler from OpenAPI operation extensions
98   */
99  static async resolveHandler(

1// F:\zApps\valtown.servers\APIServer\src\core\auth.config.ts
2
3import type { AuthorizationConfig, CsrfConfig } from "@/types/index.ts";
4
5export const AUTH_METHODS_CONFIG = {
6  // API Key Authentication
7  API_KEY: {
8    enabled: true,
9    keys: {
10      internal: Deno.env.get("INTERNAL_API_KEY") || "internal-key-change-in-production",
11      serviceToService: Deno.env.get("SERVICE_TO_SERVICE_KEY") || "s2s-key-change-in-production",
12      webhook: Deno.env.get("WEBHOOK_SECRET") || "webhook-secret-change-in-production",
13    },
14    headerNames: ["X-API-Key", "Authorization"],
15    queryParamNames: ["apiKey", "api_key"],
16    defaultScopes: ["api:read", "api:write"],
17  },
18
162
163export const JWT_CONFIG = {
164  // Public API JWT
165  API: {
166    enabled: true,
167    secretKey: Deno.env.get("JWT_SECRET") || "your-secret-key-change-in-production",
168    algorithm: "HS256" as const,
169    issuer: Deno.env.get("JWT_ISSUER") || "val.town-api",
170    audience: Deno.env.get("JWT_AUDIENCE") || "val.town-users",
171    expiresIn: Deno.env.get("JWT_EXPIRES_IN") || "1h",
206      AUTHORIZE_URL: "https://github.com/login/oauth/authorize",
207      TOKEN_URL: "https://github.com/login/oauth/access_token",
208      USER_INFO_URL: "https://api.github.com/user",
209      ENABLED: !!(Deno.env.get("GITHUB_CLIENT_ID") && Deno.env.get("GITHUB_CLIENT_SECRET")),
210    },
216      SCOPE: "openid email profile",
217      AUTHORIZE_URL: "https://accounts.google.com/o/oauth2/v2/auth",
218      TOKEN_URL: "https://oauth2.googleapis.com/token",
219      USER_INFO_URL: "https://www.googleapis.com/oauth2/v1/userinfo",
220      ENABLED: !!(Deno.env.get("GOOGLE_CLIENT_ID") && Deno.env.get("GOOGLE_CLIENT_SECRET")),
221    },
227      SCOPE: "user-read-email user-read-private",
228      AUTHORIZE_URL: "https://accounts.spotify.com/authorize",
229      TOKEN_URL: "https://accounts.spotify.com/api/token",
230      USER_INFO_URL: "https://api.spotify.com/v1/me",
231      ENABLED: !!(Deno.env.get("SPOTIFY_CLIENT_ID") && Deno.env.get("SPOTIFY_CLIENT_SECRET")),
232    },

1// F:\zApps\valtown.servers\APIServer\src\core\auth.types.ts
2
3import type { JWTPayload as JoseLibJWTPayload } from "jose";
7  | "basic"
8  | "oauth"
9  | "apiKey"
10  | "internal"
11  | "webhook"
389
390// ============================================================================
391// API KEY AUTHENTICATION TYPES
392// ============================================================================
393
394/**
395 * API Key configuration
396 */
397export interface ApiKeyConfig {
398  enabled: boolean;
399  keys: Record<
414 */
415export interface AuthMethodsConfig {
416  API_KEY: ApiKeyConfig;
417  BASIC: BasicAuthConfig;
418  SESSION: CookieSessionConfig; // Assuming this is the one used in config
421
422/**
423 * JWT configurations (for API and Internal usage)
424 */
425export interface JwtConfigurations {
426  API: {
427    enabled: boolean;
428    secretKey: string;

1// F:\zApps\valtown.servers\APIServer\src\core\app.types.ts
2import type { Context } from "hono";
3import { HTTPException } from "hono/http-exception";
13}
14
15export interface ApiResponse<T = unknown> {
16  success: boolean;
17  data?: T;
135
136// ============================================================================
137// API Configuration Types
138// ============================================================================
139export interface ApiConfig {
140  PUBLIC_API_PREFIX: string;
141  INTERNAL_API_PREFIX: string;
142  WEBHOOK_PREFIX: string;
143  CALLBACK_PREFIX: string;
196// ============================================================================
197export interface TavilyServiceConfig {
198  API_KEY?: string;
199  BASE_URL: string;
200  TIMEOUT: number;
203
204export interface FirecrawlServiceConfig {
205  API_KEY?: string;
206  BASE_URL: string;
207  TIMEOUT: number;
210
211export interface OpenAIServiceConfig {
212  API_KEY?: string;
213  BASE_URL: string;
214  TIMEOUT: number;
217
218export interface ResendServiceConfig {
219  API_KEY?: string;
220  BASE_URL: string;
221  TIMEOUT: number;
235export interface AppConfigShape {
236  server: ServerConfig;
237  api: ApiConfig;
238  debug: DebugConfig;
239  logging: LoggingConfig;

1// F:\zApps\valtown.servers\APIServer\src\core\app.config.ts
2
3import type { AppConfigShape, LogLevel } from "./appTypes.ts";
6export const APP_CONFIG: AppConfigShape = {
7  server: {
8    NAME: "Secure API Server",
9    DESCRIPTION:
10      "A secure, modular API server with OAuth, storage, and external service integration",
11    VERSION: "2.0.0",
12    BASE_URL: Deno.env.get("SERVER_BASE_URL") || "https://api.ianmenethil.com",
13    ENVIRONMENT: Deno.env.get("DENO_ENV") || "development",
14    PORT: parseInt(Deno.env.get("PORT") || "8000"),
15    HOST: Deno.env.get("HOST") || "0.0.0.0",
16  },
17  api: {
18    PUBLIC_API_PREFIX: "/v1",
19    INTERNAL_API_PREFIX: "/",
20    WEBHOOK_PREFIX: "/webhooks",
21    CALLBACK_PREFIX: "/callbacks",

1// F:\zApps\valtown.servers\APIServer\src\config\index.ts
2export { APP_CONFIG, getConfig } from "../core/appConfig.ts";
3export * from "../core/appTypes.ts";

49}
50
51// API response interfaces
52export interface ApiResponse<T> {
53  success: boolean;
54  data?: T;

18- Generate code in TypeScript or TSX
19- Add appropriate TypeScript types and interfaces for all data structures
20- Prefer official SDKs or libraries than writing API calls directly
21- Ask the user to supply API or library documentation if you are at all unsure about it
22- **Never bake in secrets into the code** - always use environment variables
23- Include comments explaining complex logic (avoid commenting obvious operations)
28### 1. HTTP Trigger
29
30- Create web APIs and endpoints
31- Handle HTTP requests and responses
32- Example structure:
138However, it's *extremely importing* to note that `parseProject` and other Standard Library utilities ONLY RUN ON THE SERVER.
139If you need access to this data on the client, run it in the server and pass it to the client by splicing it into the HTML page
140or by making an API request for it.
141
142## Val Town Platform Specifics
146- **AI Image:** To inline generate an AI image use: `<img src="https://maxm-imggenurl.web.val.run/the-description-of-your-image" />`
147- **Storage:** DO NOT use the Deno KV module for storage
148- **Browser APIs:** DO NOT use the `alert()`, `prompt()`, or `confirm()` methods
149- **Weather Data:** Use open-meteo for weather data (doesn't require API keys) unless otherwise specified
150- **View Source:** Add a view source link by importing & using `import.meta.url.replace("ems.sh", "val.town)"` (or passing this data to the client) and include `target="_top"` attribute
151- **Error Debugging:** Add `<script src="https://esm.town/v/std/catch"></script>` to HTML to capture client-side errors
152- **Error Handling:** Only use try...catch when there's a clear local resolution; Avoid catches that merely log or return 500s. Let errors bubble up with full context
153- **Environment Variables:** Use `Deno.env.get('keyname')` when you need to, but generally prefer APIs that don't require keys
154- **Imports:** Use `https://esm.sh` for npm and Deno dependencies to ensure compatibility on server and browser
155- **Storage Strategy:** Only use backend storage if explicitly required; prefer simple static client-side sites
376### Backend (Hono) Best Practices
377
378- Hono is the recommended API framework
379- Main entry point should be `main.tsx`
380- **Database Setup:** Use the admin utilities to handle table creation and seeding. Backend should focus on CRUD operations only
402  });
403  ```
404- Create RESTful API routes for CRUD operations
405- Always include this snippet at the top-level Hono app to re-throwing errors to see full stack traces:
406  ```ts
442   - For files in the project, use `readFile` helpers
443
4445. **API Design:**
445   - `fetch` handler is the entry point for HTTP vals
446   - Run the Hono app with `export default app.fetch // This is the entry point for HTTP vals`

68---
69
70## Phase 2: Core Backend API
71**Goal**: Build RESTful API endpoints for invoice management
72
73### Tasks:
741. **Main API Setup**
75   - Create `main.tsx` with Hono app configuration
76   - Set up error handling and static file serving
77   - Configure CORS if needed
78
792. **Invoice API Endpoints**
80   - `GET /api/invoices` - List all invoices with filtering
81   - `POST /api/invoices` - Create new invoice
82   - `PUT /api/invoices/:id` - Update invoice (mainly status changes)
83   - `DELETE /api/invoices/:id` - Delete invoice
84   - `GET /api/invoices/stats` - Dashboard statistics
85
863. **Vendor API Endpoints**
87   - `GET /api/vendors` - List all vendors
88   - `PUT /api/vendors/:id` - Update vendor name
89
90### Deliverables:
91- Complete REST API for invoice management
92- API endpoints tested via admin tools or direct calls
93- Proper error handling and validation
94
182
183## Technical Stack
184- **Backend**: Hono.js for API routes
185- **Database**: SQLite with Val Town's sqlite service
186- **Frontend**: React 18.2.0 with TypeScript
207
2081. **Phase 1: Foundation & Database Setup** - Get the core database structure and admin tools working
2092. **Phase 2: Core Backend API** - Build the REST API endpoints for managing invoices and vendors
2103. **Phase 3: Frontend Foundation** - Create the basic React UI with invoice display and forms
2114. **Phase 4: Enhanced UI & Interactions** - Add advanced features like dashboard, filtering, and bulk operations
223- Uses Val Town best practices with proper project structure
224- SQLite database with proper schema and constraints
225- Hono.js backend with RESTful API design
226- React frontend with TailwindCSS for styling
227- Admin utilities for easy database management and seeding
238- add a checkbox that the llm can mark off after completeing a phase.
239- no need for code to "Update vendor name" i will do that manually in admin code
240- no need to "   - `DELETE /api/invoices/:id` - Delete invoice" , i'll do that using SQL commands , so add to plan to create a section in "db-tools.tsx" with some SQL commands that i can easily copy to run and a link to the database explorer "https://arfan25-admin-sqliteexplorerapp.val.run/"
241
242---
261## Phase Completion Checklist
262- [ ] Phase 1: Foundation & Database Setup
263- [ ] Phase 2: Core Backend API  
264- [ ] Phase 3: Frontend Foundation
265- [ ] Phase 4: Enhanced UI & Interactions
284
285```markdown
2862. **Invoice API Endpoints**
287   - `GET /api/invoices` - List all invoices with filtering
288   - `POST /api/invoices` - Create new invoice
289   - `PUT /api/invoices/:id` - Update invoice (mainly status changes)
290   - `DELETE /api/invoices/:id` - Delete invoice
291   - `GET /api/invoices/stats` - Dashboard statistics
292
2933. **Vendor API Endpoints**
294   - `GET /api/vendors` - List all vendors
295   - `PUT /api/vendors/:id` - Update vendor name
296
297->
298
2992. **Invoice API Endpoints**
300   - `GET /api/invoices` - List all invoices with filtering
301   - `POST /api/invoices` - Create new invoice
302   - `PUT /api/invoices/:id` - Update invoice (mainly status changes)
303   - `GET /api/invoices/stats` - Dashboard statistics
304
3053. **Vendor API Endpoints**
306   - `GET /api/vendors` - List all vendors
307```
308
353```markdown
354## Technical Stack
355- **Backend**: Hono.js for API routes
356- **Database**: SQLite with Val Town's sqlite service
357- **Frontend**: React 18.2.0 with TypeScript
362
363## Technical Stack
364- **Backend**: Hono.js for API routes
365- **Database**: SQLite with Val Town's sqlite service
366- **Frontend**: React 18.2.0 with TypeScript
406- Updated technical stack to mention DaisyUI, nord theme, and Iconify v3
407
408✅ **Removed vendor name update API** - No longer planning to build `PUT /api/vendors/:id` endpoint since you'll handle this manually in admin tools
409
410✅ **Removed delete invoice API** - No longer planning `DELETE /api/invoices/:id` endpoint since you'll use SQL commands directly
411
412✅ **Enhanced admin tools** - Added to Phase 1: